Skip to content
Tutorials Center
My learning

Topics

Lesson 38 of 38 ยท Projects and Practice

Emacs Troubleshooting, Bisecting Config and Performance Tuning

Find and fix Emacs problems: read backtraces, bisect a broken config, profile slow commands, cut startup time, and handle long lines and large files.

Every Emacs user eventually meets a broken key, a package that misbehaves or a buffer that freezes. The good news is that Emacs is the most inspectable editor there is: every key, variable and function can be examined while it runs. This final lesson gives you a systematic method for diagnosing problems, bisecting your configuration, and making Emacs faster.

Commands are real. The runnable blocks are JavaScript stand-ins that model bisecting a configuration and a startup-time report.

Step 1: ask Emacs what happened

Start with the built-in questions:

  • What does this key do? C-h k then the key. What did I just press? C-h l (view-lossage).
  • What is bound here? C-h b lists bindings; C-h m describes the active modes and their keys.
  • What is this variable's value and who set it? C-h v. What does this function do? C-h f. Both show the file where it is defined and a link to the source.
  • What went wrong? Look at the *Messages* buffer (C-h e) and *Warnings*.
  • Show me a backtrace. M-x toggle-debug-on-error before repeating the failing action. In the *Backtrace* buffer, read from the top: the first frames show the failing function; q quits. To catch a quit loop (a hang), press C-g repeatedly, or set debug-on-quit with M-x toggle-debug-on-quit and press C-g while it hangs to see where it is stuck.
  • Is the init file the problem? Start emacs -Q (no config). If the problem disappears, it is your configuration or a package; if it remains, it is Emacs, the terminal or the OS.
  • Where does an error in init come from? emacs --debug-init.

Step 2: bisect your configuration

When you do not know which line of the init file is responsible, do a binary search: disable half, test, repeat. Each round halves the suspects, so even 200 forms need only about eight tests. Packages exist to automate this (for example bug-hunter), or do it by hand: put (error "stop") or (setq debug-on-error t) halfway, or comment out blocks, and test with emacs --debug-init.

JS Stand-in: bisect a configuration

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Common culprits: a package whose version changed, a setq of a variable that a newer Emacs renamed, a hook function that errors (which stops later functions in that hook), key bindings that shadow a mode's keys, and exec-path or PATH missing a tool Emacs cannot find. After you find it, report a bug with M-x report-emacs-bug (Emacs) or open an issue with the package, including the output of M-x emacs-version and a minimal emacs -Q recipe.

Step 3: measure startup

M-x emacs-init-time prints the startup time. To see where it goes, try the package benchmark-init or Emacs's own profiler:

ELISP
;; at the very top of init.el
(defvar my/start (current-time))
;; at the very bottom of init.el
(message "init.el took %.2fs" (float-time (time-subtract (current-time) my/start)))

Typical fixes, in order of impact:

  1. Defer packages. Use use-package with :bind, :hook, :mode or :commands, so a package loads only when needed.
  2. Raise the garbage-collection threshold during startup, as in early-init.el: (setq gc-cons-threshold (* 64 1024 1024)), and reset to a moderate value (for example 16 MB) afterwards with (add-hook 'emacs-startup-hook (lambda () (setq gc-cons-threshold (* 16 1024 1024)))).
  3. Use native compilation. Emacs 28+ built with --with-native-compilation compiles packages to machine code in the background and caches them in ~/.emacs.d/eln-cache/. Check with (native-comp-available-p).
  4. Avoid heavy work at startup: network calls, large require chains, package-refresh-contents on every start.
  5. Use the daemon. If starting takes one second, you pay it once a day (the server).
JS Stand-in: a startup time report

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Step 4: profile a slow command

If typing or a command is sluggish, use the built-in profiler:

  1. M-x profiler-start RET cpu RET (or cpu+mem).
  2. Do the slow thing for a few seconds.
  3. M-x profiler-report. Expand with TAB (or RET); the entries with the highest percentage show where time goes, and j jumps to a function's definition.
  4. M-x profiler-stop.

Typical findings: a font-lock rule that is too complex, flyspell or flymake running on every keystroke, a mode-line :eval that does real work, or a hook doing synchronous I/O.

Large files and long lines

Emacs slows down badly on lines that are thousands of characters long (minified JavaScript, JSON on one line). Emacs 27+ includes so-long-mode, which turns off expensive features automatically when it detects such a file: (global-so-long-mode 1). For a huge file, open it with M-x find-file-literally, use M-x vlf (View Large Files, a package) or M-x fundamental-mode, and turn off line-number-mode and global-font-lock-mode in that buffer. Set (setq bidi-paragraph-direction 'left-to-right) and (setq-default bidi-display-reordering nil) to speed up display of long lines if you never edit right-to-left text.

Process output can also be slow: raise read-process-output-max ((setq read-process-output-max (* 1024 1024))), which helps LSP servers talk to Eglot.

Recovering

  • Frozen Emacs: press C-g several times; on Linux send SIGUSR2 (pkill -USR2 emacs) to force a debugger entry; a stuck Elisp loop can be interrupted this way.
  • Crash: M-x recover-session or recover-this-file restores auto-saved text.
  • Broken packages after an upgrade: delete the elpa folder or the single package folder and reinstall, then delete *.elc files if byte code is stale.
  • Corrupt state: move ~/.emacs.d aside and keep only init.el to start fresh.

Keep a text note "Emacs problems I solved" in your notes. Next time the symptom returns you will find the fix in seconds; many Emacs problems recur after upgrades.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the first test when something odd happens and you suspect your configuration?

    emacs -Q skips your configuration; if the problem disappears, the configuration or a package is responsible.
  2. 2. Which command shows a backtrace when an error is signalled?

    toggle-debug-on-error opens the Backtrace buffer at the failing point.
  3. 3. How many tests does binary search need to find one culprit among 64 config blocks?

    Each test halves the suspects: 64 -> 32 -> 16 -> 8 -> 4 -> 2 -> 1, which is six tests.
  4. 4. What does so-long-mode do?

    so-long-mode detects very long lines and turns off costly modes so the buffer stays usable.

Summary

  • Ask Emacs: C-h k, C-h l, C-h v, C-h f, *Messages*, toggle-debug-on-error.
  • emacs -Q separates a configuration problem from an Emacs problem; --debug-init pinpoints init errors.
  • Bisect by halving the suspects; it takes about log2(n) tests.
  • Speed startup by deferring packages, tuning garbage collection, using native compilation and a daemon.
  • Use the profiler for slow commands and so-long-mode for long lines.

Next: Emacs course overview