19.1.2 Debugging Redisplay Errors

When an error occurs in Lisp code which redisplay has invoked, Emacs's usual debugging mechanisms are unusable, for technical reasons. This subsection describes how to get a backtrace from such an error, which should be helpful in debugging it.

These directions apply to Lisp forms used, for example, in :eval mode line constructs (see The Data Structure of the Mode Line), and in all hooks invoked from redisplay, such as:

• fontification-functions (see Automatic Face Assignment).
• window-scroll-functions (see Hooks for Window Scrolling and Changes).

Note that if you have had an error in a hook function called from redisplay, the error handling might have removed this function from the hook. You will thus need to reinitialize that hook somehow, perhaps with add-hook, to be able to replay the bug.

To generate a backtrace in these circumstances, set the variable backtrace-on-redisplay-error to non-nil. When the error occurs, Emacs will dump the backtrace to the buffer *Redisplay-trace*, but won't automatically display it in a window. This is to avoid needlessly corrupting the redisplay you are debugging. You will thus need to display the buffer yourself, with a command such as switch-to-buffer-other-frame C-x 5 b.

Variable: backtrace-on-redisplay-error

Set this variable to non-nil to enable the generation of a backtrace when an error occurs in any Lisp called from redisplay.