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 signal Lisp errors when invoked inappropriately, and during ordinary editing it would be very inconvenient to enter the debugger each time this happens. So if you want errors to enter the debugger, set the variable
debug-on-error to non-
nil. (The command
toggle-debug-on-error provides an easy way to do this.)
user option debug-on-error
This variable determines whether the debugger is called when an error is signaled and not handled. If
t, all kinds of errors call the debugger, except those listed in
debug-ignored-errors (see below). If it is
nil, none call the debugger.
The value can also be a list of error conditions (see Signaling Errors). Then the debugger is called only for error conditions in this list (except those also listed in
debug-ignored-errors). For example, if you set
debug-on-error to the list
(void-variable), the debugger is only called for errors about a variable that has no value.
eval-expression-debug-on-error overrides this variable in some cases; see below.
When this variable is non-
nil, Emacs does not create an error handler around process filter functions and sentinels. Therefore, errors in these functions also invoke the debugger. See Processes.
user option debug-ignored-errors
This variable specifies errors which should not enter the debugger, regardless of the value of
debug-on-error. 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.
The normal value of this variable includes
user-error, as well as several errors that happen often during editing but rarely result from bugs in Lisp programs. However, “rarely" is not “never"; if your program fails with an error that matches this list, you may try changing this list to debug the error. The easiest way is usually to set
user option eval-expression-debug-on-error
If this variable has a non-
nil value (the default), running the command
debug-on-error to be temporarily bound to
t. See Evaluating Emacs Lisp Expressions in The GNU Emacs Manual.
nil, then the value of
debug-on-error is not changed during
user option debug-on-signal
Normally, errors caught by
condition-case never invoke the debugger. The
condition-case gets a chance to handle the error before the debugger gets a chance.
If you change
debug-on-signal to a non-
nil value, the debugger gets the first chance at every error, regardless of the presence of
condition-case. (To invoke the debugger, the error must still fulfill the criteria specified by
For example, setting this variable is useful to get a backtrace from code evaluated by emacsclient’s
--eval option. If Lisp code evaluated by emacsclient signals an error while this variable is non-
nil, the backtrace will popup in the running Emacs.
Warning: Setting this variable to non-
nil may have annoying effects. Various parts of Emacs catch errors in the normal course of affairs, and you may not even realize that errors happen there. If you need to debug code wrapped in
condition-case, consider using
condition-case-unless-debug (see Handling Errors).
user option debug-on-event
If you set
debug-on-event to a special event (see Special Events), Emacs will try to enter the debugger as soon as it receives this event, bypassing
special-event-map. At present, the only supported values correspond to the signals
SIGUSR2 (this is the default). This can be helpful when
inhibit-quit is set and Emacs is not otherwise responding.
If you set
debug-on-message to a regular expression, Emacs will enter the debugger if it displays a matching message in the echo area. For example, this can be useful when trying to find the cause of a particular message.
To debug an error that happens during loading of the init file, use the option ‘
--debug-init’. This binds
t while loading the init file, and bypasses the
condition-case which normally catches errors in the init file.