GNU Emacs Lisp Reference Manual

15.1.1: Entering the Debugger on an Error

The most important time to enter the debugger is when a Lisp error happens. This allows you to investigate the immediate causes of the error.

However, entry to the debugger is not a normal consequence of an error. Many commands frequently get Lisp errors when invoked in inappropriate contexts (such as C-f at the end of the buffer) and during ordinary editing it would be very unpleasant to enter the debugger each time this happens. If you want errors to enter the debugger, set the variable debug-on-error to non-nil.

User Option: debug-on-error

This variable determines whether the debugger is called when an error is signaled and not handled. If debug-on-error is t, all errors call the debugger. If it is nil, none call the debugger.

The value can also be a list of error conditions that should call the debugger. For example, if you set it to the list (void-variable), then only errors about a variable that has no value invoke the debugger.

When this variable is non-nil, Emacs does not catch errors that happen in process filter functions and sentinels. Therefore, these errors also can invoke the debugger. See Processes.

To debug an error that happens during loading of the `.emacs' file, use the option `-debug-init', which binds debug-on-error to t while `.emacs' is loaded and inhibits use of condition-case to catch init file errors.

If your `.emacs' file sets debug-on-error, the effect may not last past the end of loading `.emacs'. (This is an undesirable byproduct of the code that implements the `-debug-init' command line option.) The best way to make `.emacs' set debug-on-error permanently is with after-init-hook, like this:

(add-hook 'after-init-hook
          '(lambda () (setq debug-on-error t)))