21

In a situation where Emacs is not behaving like I want, what can I do to troubleshoot the problem? What steps can I take to find and fix the problem myself?

Or, failing that, how can I gather useful information that so that people here (or on the mailing list or other forums) can help me with my problem?

My Emacs includes many packages, a collection of snippets copy & pasted (or killed & yanked) from all over the internet, and my own custom elisp, some of which I don't recall writing, or no longer understand. Is there a way to make sense of all of these complications?

  • Not sure if this is the best place for this, but there are a lot of questions that get answers/comments requesting emacs -Q as a first step. I wrote this up as something to link those questions to as generic help for new users. – Tyler Nov 4 '16 at 22:30
  • Yup, it is the best place for this. Actually, such a question was suggested (almost) 2 years ago: meta.emacs.stackexchange.com/q/198/184 Thanks! – T. Verron Nov 4 '16 at 22:46
27

Step 1: running emacs -Q

The first thing you need to do is run emacs without any of your customizations. If you can reproduce the problem in vanilla Emacs, it may actually be a bug in Emacs itself. That's rare, but we rule it out as a first step.

If you start Emacs from the command line with the -Q flag, i.e., emacs -Q, you'll get a bare or 'vanilla' emacs, with none of your local customizations loaded. Does your problem still occur? If so, skip down to "Providing a Bug Recipe".

Step 1b: what if the problem is with a package?

If your problem is specific to a particular package, then obviously you can't reproduce it without loading that package. But you want to load only the package concerned, not all of your configuration. To do that, run emacs -Q again, and prepare a short script such as the following:

(require 'package)
(setq package-load-list
      '((package1 t)))
(package-initialize)

Replace package1 with the name of the package you want to load. If you need to load multiple packages, modify the script accordingly:

(require 'package)
(setq package-load-list
      '((package1 t)
        (package2 t)
        (package3 t)))
(package-initialize)

To load this code, you can paste it into the *scratch* buffer, and call M-x eval-buffer. (or any buffer, as long as it doesn't have any other code in it!).

At this point, you've loaded the package(s), and just the package(s) you're testing. If you can reproduce the problem now, skip down to "Providing a Bug Recipe".

Step 2: Finding a Bug in your .emacs

You've now confirmed that the problem is coming from something in your configuration ("the call is coming from inside the house!"). Your configuration may be many thousands of lines long, and may load many different files. To find the problem, you'll do a binary search, commenting out half the code at a time to narrow things down.1

  1. Open your regular emacs, emacs, without the -Q option.
  2. Open your config file (usually ~/.emacs or .emacs.d/init.el, if you can't find it try C-h v user-init-file)
  3. Select the first half of the file: C-space to set the mark, scroll down half-way to extend the region
  4. Comment out the selected region: M-; and save the file
  5. Open a new emacs (your test emacs), leaving the first emacs running. test emacs will read the reduced version of your config.
  6. Try to reproduce the problem in test emacs
  7. If you can't reproduce it, close test emacs, and in your original emacs undo the comment with C-/, and comment out half of the remaining code. Open a new test emacs and try again.
  8. If you can reproduce the problem, comment out half of the remaining code and see if the problem persists.
  9. Repeat this process until you find the smallest bit of your configuration necessary to reproduce the problem.

If your problem is with a specific package, you'll have to leave the code that loads that package uncommented, of course.

If your config file loads other files, you may end up extending your search into those files as well.

At this point, you may have found that the problem is due to just a line or two of code. You may even be able to fix it yourself. If so, congratulations, you've learned something! Otherwise, move along to step three.

Step 3: Providing a Bug Recipe

At this point, you should be able to provide a detailed bug recipe to post here. It should include:

  • Your Emacs version (you can get this from Emacs with M-x emacs-version
  • Your operating system (Windows #, Mac, Linux distribution)
  • The version of the package your struggling with, if applicable
  • The specific steps necessary to demonstrate the problem, including what you expect to happen, and what actually happens.

For example, I might post a question like this:

I'm having a problem with super-mode. When I use M-x sm-compile-code, it makes a withdrawal from my PayPal account.

Steps to reproduce:

Load super-mode:

(require 'package)
(setq package-load-list
      '((super-mode t)))
(package-initialize)
  • open a new file with C-x C-f my-code
  • enter a line of code:
10 goto 10
  • call M-x sm-compile-code

I expect this to invoke the super-compiler and compile my program. Instead, I see a message in the minibuffer "$100 transfered from paypal to super-mode author"

GNU Emacs 25.1.50.3
Debian Linux
Super-mode version 3.1415


1The Bug Hunter package might help you with this, (semi-)automatically bisecting your init file.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.