How to find a bug in ".emacs" or "init.el"?

Question

Sometimes when I open Emacs, Emacs initialization fail.
That is because .emacs or init.el files have a bug. (My bugs often come from just mistyping.)

I want to find the bug in .emacs or init.el. Is there any way to do this?

Answer 1

To find out what part of your init file (~/.emacs) is causing the behavior you see, bisect your init file recursively: First comment-out half, to see which half is responsible, then 3/4, to see which quarter is responsible,...

To comment out a region of text (e.g. succession of lines that you have selected), I recommend comment-region (which I bind to C-x C-;). With a numeric prefix arg it uses that many ; comment chars. With a plain prefix arg (C-u) it uncomments the region instead of commenting it.

You can also start Emacs with the command-line switch --debug-init. This will cause the debugger to open when an error is raised during Emacs startup, including while your init file is loaded. The debugger backtrace tells you which evaluation raised the error (which function was called), and it shows you which function called the function where the error was raised, which function called that one, and so on.

When you know which function is the problem, if you need to you can debug its evaluation by putting (debug-on-entry 'THE-FUNCTION) near the start of your init file. That will open the debugger when the function is entered instead of just showing what happened when the error was raised. You can then step through the debugger using d (or c to skip through a step), to see just what went wrong.

If you prefer to step through the function starting at some breakpoint, then copy the source code that defines the function to your init file, and insert (debug) at the position where you want the debugger to open.

As always, the Emacs manuals are your friends. See, for instance, node Checklist in the Emacs manual and node Invoking the Debugger in the Elisp manual.

There is another debugger also, called edebug, which is also documented in the manuals. Some people prefer it to debug. (I prefer debug.) Both are good.

Using the debugger is generally more informative if you have loaded Emacs Lisp source files rather than their byte-compiled versions. If you start investigating a particular problem using the debugger, you might want to first load the *.el (not *.elc) file(s) in question.

Answer 2

I've had great success with elisp bug hunter https://github.com/Malabarba/elisp-bug-hunter.

The most common problems are unmatched parenthesis, loading-failed packages.:

Automated error hunting

If your Emacs init file signals an error during startup, but you don’t know why, simply issue

M-x bug-hunter-init-file RET e

and The Bug Hunter will find it for you. Note that your init.el (or .emacs) must be idempotent for this to work.

Interactive hunt

If Emacs starts up without errors but something is not working as it should, invoke the same command, but choose the interactive option:

M-x bug-hunter-init-file RET i

The Bug Hunter will start a separate Emacs instance several times, and then it will ask you each time whether that instance presented the problem you have. After doing this about 5–12 times, you’ll be given the results.