Next: Infinite Loops, Up: Debugger
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 cause Lisp errors when invoked
inappropriately (such as C-f at the end of the buffer), 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.)
This variable determines whether the debugger is called when an error is signaled and not handled. If
debug-on-error
ist
, all kinds of errors call the debugger (except those listed indebug-ignored-errors
). If it isnil
, 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 create an error handler around process filter functions and sentinels. Therefore, errors in these functions also invoke the debugger. See Processes.
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. However, “rarely” is not “never”; if your program fails with an error that matches this list, you will need to change this list in order to debug the error. The easiest way is usually to set
debug-ignored-errors
tonil
.
Normally, errors that are caught by
condition-case
never run the debugger, even ifdebug-on-error
is non-nil
. In other words,condition-case
gets a chance to handle the error before the debugger gets a chance.If you set
debug-on-signal
to a non-nil
value, then the debugger gets the first chance at every error; an error will invoke the debugger regardless of anycondition-case
, if it fits the criteria specified by the values ofdebug-on-error
anddebug-ignored-errors
.Warning: This variable is strong medicine! Various parts of Emacs handle errors in the normal course of affairs, and you may not even realize that errors happen there. If you set
debug-on-signal
to a non-nil
value, those errors will enter the debugger.Warning:
debug-on-signal
has no effect whendebug-on-error
isnil
.
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.
If your init file sets debug-on-error
, the effect may
not last past the end of loading the init file. (This is an undesirable
byproduct of the code that implements the ‘--debug-init’ command
line option.) The best way to make the init file set
debug-on-error
permanently is with after-init-hook
, like
this:
(add-hook 'after-init-hook (lambda () (setq debug-on-error t)))