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.)
Note that, for technical reasons, you cannot use the facilities defined in this subsection to debug errors in Lisp that the redisplay code has invoked. See Debugging Redisplay Errors, for help with these.
This variable determines whether the debugger is called when an error
is signaled and not handled. If debug-on-error is 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 How to Signal an Error). 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.
Note that 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.
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 debug-ignored-errors to nil.
If this variable has a non-nil value (the default), running the
command eval-expression causes debug-on-error to be
temporarily bound to t. See Evaluating
Emacs Lisp Expressions in The GNU Emacs Manual.
If eval-expression-debug-on-error is nil, then the value
of debug-on-error is not changed during eval-expression.
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 debug-on-error and
debug-ignored-errors.)
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 Writing Code to Handle Errors).
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 SIGUSR1 and
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.
You can evaluate forms in the current stack frame in the
‘*Backtrace*’ buffer with the e command, and while
edebugging you can use the e and C-x C-e commands to do
something similar. By default, the debugger is inhibited by these
commands (because (re-)entering the debugger at this point will
usually take you out of the debugging context you’re in). Set
debug-allow-recursive-debug to a non-nil value to allow
these commands to enter the debugger recursively.
To debug an error that happens during loading of the init
file, use the option ‘--debug-init’. This binds
debug-on-error to t while loading the init file, and
bypasses the condition-case which normally catches errors in the
init file.