32.9. Dealing with Emacs Trouble

This section describes various conditions in which Emacs fails to work normally, and how to recognize them and correct them.

32.9.1. If DELFails 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 DEL.

When Emacs starts up using a window system, it determines automatically which key should be DEL. In some unusual cases Emacs gets the wrong information from the system. If the DEL 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.

With a window system, if the DEL key says 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, but it isn't.

On a text-only terminal, if you find the DEL 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. That should make the proper DEL key work. On a text-only terminal, if you do want to ask for help, use F1 or C-?.

To fix the problem automatically for every Emacs session, you can put one of the following lines into your .emacs file (Section 32.7). For the first case above, where DEL deletes forwards instead of backwards, use this line:

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

For the other two cases, 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. Section 32.2.2.

32.9.2. Recursive Editing Levels

Recursive editing levels are important and useful features of Emacs, but they can seem like malfunctions to the user who does 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. Section 31.26.

32.9.3. Garbage on the Screen

If the data on the screen looks wrong, the first thing to do is see whether the text is really wrong. 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 Section 32.9.4.)

Display updating problems often result from an incorrect termcap 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. Very likely there is simply insufficient padding for certain display operations. 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 termcap entry, though it could also be due to a bug in Emacs that appears for terminals that have or that lack specific features.

32.9.4. Garbage in the Text

If C-l shows that the text is wrong, try undoing the changes to it using C-x u until it gets back to a state you consider correct. Also try C-h l to find out what command you typed to produce the observed results.

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. Section 31.22.

32.9.5. Spontaneous Entry to Incremental Search

If Emacs spontaneously displays I-search: at the bottom of the screen, it means that the terminal is sending C-s and C-q according to the poorly designed xon/xoff "flow control" protocol.

If this happens to you, your best recourse is to put the terminal in a mode where it will not use flow control, or give it so much padding that it will never send a C-s. (One way to increase the amount of padding is to set the variable baud-rate to a larger value. Its value is the terminal output speed, measured in the conventional units of baud.)

If you don't succeed in turning off flow control, the next best thing is to tell Emacs to cope with it. To do this, call the function enable-flow-control.

Typically there are particular terminal types with which you must use flow control. You can conveniently ask for flow control on those terminal types only, using enable-flow-control-on. For example, if you find you must use flow control on VT-100 and H19 terminals, put the following in your .emacs file:

(enable-flow-control-on "vt100" "h19")

When flow control is enabled, you must type C-\ to get the effect of a C-s, and type C-^ to get the effect of a C-q. (These aliases work by means of keyboard translations; see Section 32.5.)

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

Once you have saved your modified buffers, you can exit this Emacs job and start another, or you can use M-x kill-some-buffers to free space in the current Emacs job. If you kill buffers containing a substantial amount of text, you can safely go on editing. Emacs refills its memory reserve automatically when it sees sufficient free space available, in case you run out of memory another time.

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 memory itself, and the reserve supply may not be enough.

32.9.7. 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 asks about each of the files that you were editing during that session; 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.

32.9.8. Emergency Escape

Because at times there have been bugs causing Emacs to loop without checking quit-flag, a special feature causes Emacs to be suspended immediately if you type a second C-g while the flag is already set, so you can always get out of GNU Emacs. Normally Emacs recognizes and clears quit-flag (and quits!) quickly enough to prevent this from happening. (On MS-DOS and compatible systems, type C-BREAK twice.)

When you resume Emacs after a suspension caused by multiple C-g, 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 y to Abort (and dump core)? causes an illegal instruction to be executed, 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 n, execution does continue. With luck, GNU Emacs will ultimately check quit-flag and quit normally. If not, and you type another C-g, it is suspended 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 arrive at your former state. Presumably the quit you requested will happen soon.

The double-C-g feature is turned off when Emacs is running under the X Window System, since you can use the window manager to kill Emacs or to create another window and run another program.

On MS-DOS and compatible systems, the emergency escape feature is sometimes unavailable, even if you press C-BREAK twice, when some system call (MS-DOS or BIOS) hangs, or when Emacs is stuck in a very tight endless loop (in C code, not in Lisp code).

32.9.9. 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 doctor will help you feel better. Each time you say something to the doctor, you must end it by typing RET RET. This lets the doctor know you are finished.