elisp: Error Debugging
17.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 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 ‘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 (
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.
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.
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 ‘debug-ignored-errors’ to ‘nil’.
-- User Option: eval-expression-debug-on-error
If this variable has a non-‘nil’ value (the default), running the
command ‘eval-expression’ causes ‘debug-on-error’ to be temporarily
bound to to ‘t’. Evaluating Emacs-Lisp Expressions
(emacs)Lisp Eval.
If ‘eval-expression-debug-on-error’ is ‘nil’, then the value of
‘debug-on-error’ is not changed during ‘eval-expression’.
-- 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 ‘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’ (Handling Errors).
-- User Option: debug-on-event
If you set ‘debug-on-event’ to a special event (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.
-- Variable: debug-on-message
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 ‘debug-on-error’ to ‘t’ while
loading the init file, and bypasses the ‘condition-case’ which normally
catches errors in the init file.
Info Catalog
elisp: Debugger
elisp: Infinite Loops