22.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, SXEmacs does not catch errors that happen in process filter functions and sentinels. Therefore, these errors also can invoke the debugger. See Processes.

User Option: debug-on-signal

This variable is similar to debug-on-error but breaks whenever an error is signalled, regardless of whether it would be handled.

User Option: debug-ignored-errors

This variable specifies certain kinds of errors that should not enter the debugger. Its value is a list of error condition symbols and/or regular expressions. If the error has any of those condition symbols, or if the error message matches any of the regular expressions, then that error does not enter the debugger, regardless of the value of debug-on-error.

The normal value of this variable lists several errors that happen often during editing but rarely result from bugs in Lisp programs.

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)))