How do I troubleshoot Emacs problems?

Question

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?

Answer 1

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".

Note: emacs -q

While emacs -Q runs emacs without any customizations, emacs -q runs it without user customizations, but still runs site customizations. If you have a bug that occurs with emacs -q, but not emacs -Q, then the problem is in your site config. In that case, you need to find the file site-start.el. It's location depends on your OS. Some Linux distributions put it in /etc/emacs/. It may also be in /usr/local/share/emacs/site-lisp/. The locate command line program may be helpful in tracking it down.

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. 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 you are 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

---

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