GNU Info

(elisp)Error Debugging

---

Next: Infinite Loops Up: Debugger

---

Enter node , (file) or (file)node

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

 - 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').  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', Emacs does not create an error
     handler around process filter functions and sentinels.  Therefore,
     errors in these functions also invoke the debugger.  Note:
     Processes.

 - 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.
     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' to `nil'.

 - User Option: debug-on-signal
     Normally, errors that are caught by `condition-case' never run the
     debugger, even if `debug-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 any `condition-case', if it fits
     the criteria specified by the values of `debug-on-error' and
     `debug-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 when `debug-on-error'
     is `nil'.

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