59. Dealing with Emacs Trouble

This section describes various conditions in which Emacs fails to work normally, and how to recognize them and correct them. For a list of additional problems you might encounter, see (efaq)Bugs and problems section `Bugs and problems' in GNU Emacs FAQ, and the file `etc/PROBLEMS' in the Emacs distribution. Type C-h C-f to read the FAQ; type C-h C-e to read the `PROBLEMS' file.

59.1 If DEL Fails to Delete

Every keyboard has a large key, a little ways above the RET or ENTER key, which you normally use outside Emacs to erase the last character that you typed. We call this key the usual erasure key. In Emacs, it is supposed to be equivalent to DEL, and when Emacs is properly configured for your terminal, it translates that key into the character DEL.

When Emacs starts up on a graphical display, it determines automatically which key should be DEL. In some unusual cases Emacs gets the wrong information from the system. If the usual erasure key deletes forwards instead of backwards, that is probably what happened--Emacs ought to be treating the DELETE key as DEL, but it isn't.

On a graphical display, if the usual erasure key is labeled BACKSPACE and there is a DELETE key elsewhere, but the DELETE key deletes backward instead of forward, that too suggests Emacs got the wrong information--but in the opposite sense. It ought to be treating the BACKSPACE key as DEL, and treating DELETE differently, but it isn't.

On a text-only terminal, if you find the usual erasure key prompts for a Help command, like Control-h, instead of deleting a character, it means that key is actually sending the BS character. Emacs ought to be treating BS as DEL, but it isn't.

In all of those cases, the immediate remedy is the same: use the command M-x normal-erase-is-backspace-mode. This toggles between the two modes that Emacs supports for handling DEL, so if Emacs starts in the wrong mode, this should switch to the right mode. On a text-only terminal, if you want to ask for help when BS is treated as DEL, use F1; C-? may also work, if it sends character code 127.

To fix the problem automatically for every Emacs session, you can put one of the following lines into your `.emacs' file (see section The Init File, `~/.emacs'). For the first case above, where DELETE deletes forwards instead of backwards, use this line to make DELETE act as DEL (resulting in behavior compatible with Emacs 20 and previous versions):

(normal-erase-is-backspace-mode 0)

For the other two cases, where BACKSPACE ought to act as DEL, use this line:

(normal-erase-is-backspace-mode 1)

Another way to fix the problem for every Emacs session is to customize the variable normal-erase-is-backspace: the value t specifies the mode where BS or BACKSPACE is DEL, and nil specifies the other mode. See section Easy Customization Interface.

On a graphical display, it can also happen that the usual erasure key is labeled BACKSPACE, there is a DELETE key elsewhere, and both keys delete forward. This probably means that someone has redefined your BACKSPACE key as a DELETE key. With X, this is typically done with a command to the xmodmap program when you start the server or log in. The most likely motive for this customization was to support old versions of Emacs, so we recommend you simply remove it now.

59.2 Recursive Editing Levels

Recursive editing levels are important and useful features of Emacs, but they can seem like malfunctions if you do not understand them.

If the mode line has square brackets `[…]' around the parentheses that contain the names of the major and minor modes, you have entered a recursive editing level. If you did not do this on purpose, or if you don't understand what that means, you should just get out of the recursive editing level. To do so, type M-x top-level. This is called getting back to top level. See section Recursive Editing Levels.

59.3 Garbage on the Screen

If the text on a text terminal looks wrong, the first thing to do is see whether it is wrong in the buffer. Type C-l to redisplay the entire screen. If the screen appears correct after this, the problem was entirely in the previous screen update. (Otherwise, see the following section.)

Display updating problems often result from an incorrect terminfo entry for the terminal you are using. The file `etc/TERMS' in the Emacs distribution gives the fixes for known problems of this sort. `INSTALL' contains general advice for these problems in one of its sections. To investigate the possibility that you have this sort of problem, try Emacs on another terminal made by a different manufacturer. If problems happen frequently on one kind of terminal but not another kind, it is likely to be a bad terminfo entry, though it could also be due to a bug in Emacs that appears for terminals that have or that lack specific features.

59.4 Garbage in the Text

If C-l shows that the text is wrong, first type C-h l to see what commands you typed to produce the observed results. Then try undoing the changes step by step using C-x u, until it gets back to a state you consider correct.

If a large portion of text appears to be missing at the beginning or end of the buffer, check for the word `Narrow' in the mode line. If it appears, the text you don't see is probably still present, but temporarily off-limits. To make it accessible again, type C-x n w. See section Narrowing.

59.5 Running out of Memory

If you get the error message `Virtual memory exceeded', save your modified buffers with C-x s. This method of saving them has the smallest need for additional memory. Emacs keeps a reserve of memory which it makes available when this error happens; that should be enough to enable C-x s to complete its work. When the reserve has been used, `!MEM FULL!' appears at the beginning of the mode line, indicating there is no more reserve.

Once you have saved your modified buffers, you can exit this Emacs session and start another, or you can use M-x kill-some-buffers to free space in the current Emacs job. If this frees up sufficient space, Emacs will refill its memory reserve, and `!MEM FULL!' will disappear from the mode line. That means you can safely go on editing in the same Emacs session.

Do not use M-x buffer-menu to save or kill buffers when you run out of memory, because the buffer menu needs a fair amount of memory itself, and the reserve supply may not be enough.

59.6 Recovery After a Crash

If Emacs or the computer crashes, you can recover the files you were editing at the time of the crash from their auto-save files. To do this, start Emacs again and type the command M-x recover-session.

This command initially displays a buffer which lists interrupted session files, each with its date. You must choose which session to recover from. Typically the one you want is the most recent one. Move point to the one you choose, and type C-c C-c.

Then recover-session considers each of the files that you were editing during that session; for each such file, it asks whether to recover that file. If you answer y for a file, it shows the dates of that file and its auto-save file, then asks once again whether to recover that file. For the second question, you must confirm with yes. If you do, Emacs visits the file but gets the text from the auto-save file.

When recover-session is done, the files you've chosen to recover are present in Emacs buffers. You should then save them. Only this--saving them--updates the files themselves.

As a last resort, if you had buffers with content which were not associated with any files, or if the autosave was not recent enough to have recorded important changes, you can use the `etc/emacs-buffer.gdb' script with GDB (the GNU Debugger) to retrieve them from a core dump-provided that a core dump was saved, and that the Emacs executable was not stripped of its debugging symbols.

As soon as you get the core dump, rename it to another name such as `core.emacs', so that another crash won't overwrite it.

To use this script, run gdb with the file name of your Emacs executable and the file name of the core dump, e.g. `gdb /usr/bin/emacs core.emacs'. At the (gdb) prompt, load the recovery script: `source /usr/src/emacs/etc/emacs-buffer.gdb'. Then type the command ybuffer-list to see which buffers are available. For each buffer, it lists a buffer number. To save a buffer, use ysave-buffer; you specify the buffer number, and the file name to write that buffer into. You should use a file name which does not already exist; if the file does exist, the script does not make a backup of its old contents.

59.7 Emergency Escape

On text-only terminals, the emergency escape feature suspends Emacs immediately if you type C-g a second time before Emacs can actually respond to the first one by quitting. This is so you can always get out of GNU Emacs no matter how badly it might be hung. When things are working properly, Emacs recognizes and handles the first C-g so fast that the second one won't trigger emergency escape. However, if some problem prevents Emacs from handling the first C-g properly, then the second one will get you back to the shell.

When you resume Emacs after a suspension caused by emergency escape, it asks two questions before going back to what it had been doing:

Auto-save? (y or n)
Abort (and dump core)? (y or n)

Answer each one with y or n followed by RET.

Saying y to `Auto-save?' causes immediate auto-saving of all modified buffers in which auto-saving is enabled. Saying n skips this.

Saying y to `Abort (and dump core)?' causes Emacs to crash, dumping core. This is to enable a wizard to figure out why Emacs was failing to quit in the first place. Execution does not continue after a core dump.

If you answer this question n, Emacs execution resumes. With luck, Emacs will ultimately do the requested quit. If not, each subsequent C-g invokes emergency escape again.

If Emacs is not really hung, just slow, you may invoke the double C-g feature without really meaning to. Then just resume and answer n to both questions, and you will get back to the former state. The quit you requested will happen by and by.

Emergency escape is active only for text terminals. On graphical displays, you can use the mouse to kill Emacs or switch to another program.

On MS-DOS, you must type C-BREAK (twice) to cause emergency escape--but there are cases where it won't work, when system call hangs or when Emacs is stuck in a tight loop in C code.

59.8 Help for Total Frustration

If using Emacs (or something else) becomes terribly frustrating and none of the techniques described above solve the problem, Emacs can still help you.

First, if the Emacs you are using is not responding to commands, type C-g C-g to get out of it and then start a new one.

Second, type M-x doctor RET.

The Emacs psychotherapist will help you feel better. Each time you say something to the psychotherapist, you must end it by typing RET RET. This indicates you are finished typing.

This document was generated by Mark Kaminski on July, 3 2008 using texi2html 1.70.