Emacs Troubleshooting Guide - Fix the Most Common Issues That Make You Want to Throw Your Laptop Out the Window

The Nuclear Option: Starting Fresh

When your config is so fucked that even --debug-init doesn't help, sometimes you need to start over. But you don't have to lose everything you've built.

First, back up your current disaster: cp ~/.emacs.d ~/.emacs.d.broken. Now you can always go back if things get worse (they probably will).

Start with Doom Emacs or Spacemacs as a base. I know, I know - "real Emacs users build from scratch." But these frameworks solve 90% of the configuration problems that make people give up on Emacs. You can always customize later once you're not debugging basic functionality.

Package Hell and How to Escape It

The worst part about Emacs isn't learning the keybindings. It's when packages start fighting each other and you have no idea why your editor suddenly can't do basic shit like syntax highlighting or completion.

Rule #1: Use use-package for everything. It manages loading order, keybindings, and dependencies automatically. Without it, you're manually managing load order like it's 1985.

Rule #2: Pin your package versions. Add this to avoid surprise breakage:

(setq package-archives '((\"melpa-stable\" . \"https://stable.melpa.org/packages/\")
                         (\"gnu\" . \"https://elpa.gnu.org/packages/\")))

Rule #3: When a package breaks, check its GitHub issues before spending hours debugging. Someone else probably hit the same problem and posted a workaround. The use-package troubleshooting guide covers common configuration errors.

Performance Tuning That Actually Works

Native compilation in Emacs 28+ is huge, but there are still things that'll make your editor feel sluggish:

• Line numbers on huge files: (setq display-line-numbers-type nil) when editing massive logs
• Auto-save every keystroke: (setq auto-save-timeout 300) saves every 5 minutes instead of constantly
• Company mode being too eager: (setq company-idle-delay 0.5) waits half a second before showing completions

The big one that nobody talks about: Git status in your modeline. Packages like magit and doom-modeline check git status constantly. In huge repos, this destroys performance. Turn it off: (setq doom-modeline-vcs-max-length 12). For more performance fixes that actually work, check the LSP Mode performance guide and Emacs startup optimization strategies.

When LSP Servers Go Wrong

Eglot is built-in now, but LSP servers are still temperamental pieces of shit that crash for no reason. When your code completion stops working:

1. M-x eglot-reconnect fixes 60% of issues
2. Check *EGLOT* buffer for error messages
3. Kill the LSP server process: pkill -f \"language-server-name\"
4. Update the LSP server - old versions break with new Emacs releases

Pro tip: Keep a `.dir-locals.el` in your project root with LSP settings. This way project-specific config doesn't pollute your global setup. For when you really need to dig into the guts of things, check out Edebug documentation and the Emacs Package Developer's Handbook.

Production Debugging

• When You Need Emacs Working Now

The "Oh Shit" Debugging Toolkit

When your Emacs setup breaks in production (yeah, some of us use Emacs on servers, deal with it), you need diagnostics that work without a GUI, without your fancy packages, and without Stack Overflow.

I've been there

• remote server, deadline tomorrow, and my editor won't even start.

Essential debugging commands that work in any Emacs:

• emacs --batch --eval '(message \"%s\" (emacs-version))'

• version check from command line

• M-x toggle-debug-on-error

• shows stack traces when shit breaks

• M-x describe-key C-h

• figure out what the hell a keybinding actually does

• C-h f function-name

• see if a function exists and what it does

Config Bisection

• Finding the Needle in the Haystack

Your config is 500 lines long and something in there is breaking.

Binary search that shit:

Comment out the bottom half, restart Emacs

2. Still broken? Problem is in the top half. Still working? Problem is in the bottom half

3. Repeat until you find the exact line

Faster method: Split your config into multiple files and load them one by one until something breaks.

When External Tools Let You Down

Emacs integrates with everything: git, language servers, spell checkers, pdf viewers.

When these break, Emacs breaks in mysterious ways.

Check what external tools Emacs expects:

• M-x executable-find \"git\"

• is git in your PATH?

• M-x executable-find \"aspell\"

• spell checking working?

• C-h v exec-path

• does Emacs see the same PATH as your shell?

Common fix for PATH issues:

Install exec-path-from-shell and add this to your config:

(when (memq window-system '(mac ns x))
  (exec-path-from-shell-initialize))

For detailed PATH configuration troubleshooting, see the exec-path StackExchange discussion and macOS PATH configuration guide.

Debugging Package Loading Issues

Packages load in random order unless you explicitly control it.

When package A needs package B but B isn't loaded yet, you get cryptic errors.

Debug package loading:

(setq package-load-list '(all))  ; Load everything
(setq debug-on-error t)          ; Show stack traces

Or just switch to use-package and let it handle dependencies:

(use-package company
  :ensure t
  :after (lsp-mode)  ; Only load after lsp-mode is ready
  :config
  (global-company-mode))

When All Else Fails:

The Nuclear Options

Sometimes your Emacs installation is just fucked beyond repair. These are your last-resort fixes:

1. Complete package reset: rm -rf ~/.emacs.d/elpa/ and reinstall everything

2. Reset all customizations: rm ~/.emacs.d/custom.el (backs up to custom.el.bak first)

3. Fresh Emacs build:

If you're on Linux, compile Emacs from source with exactly the features you need

And the ultimate nuclear option: Doom Emacs gives you a working config in 10 minutes instead of spending weeks debugging your artisanal hand-crafted setup.

I switched to it after my custom config broke during a server migration at 2am. Pride isn't worth missing deadlines. For deeper debugging techniques, check the Elisp development practices guide and the latest Emacs 30.1 debugging features.

Remember: The goal is to get work done, not to win the "most customized Emacs" contest. Sometimes the right answer is to cut your losses and start with something that works.