Emacs Troubleshooting: AI-Optimized Technical Reference

Emergency Diagnostic Commands

Startup Issues

• Primary diagnostic: emacs --debug-init - Shows exact failure location instead of silent failures
• Clean state test: emacs -Q - Starts with zero configuration to isolate config vs Emacs issues
• Common failure: Symbol's function definition is void: use-package indicates missing package installation
• Hang debugging: pkill -f emacs then emacs --debug-init or load config incrementally

Performance Diagnostics

• CPU profiling: M-x profiler-start (cpu) → perform slow operation → M-x profiler-report
• Memory analysis: M-x memory-usage shows memory consumption by component
• Garbage collection optimization: (setq gc-cons-threshold (* 50 1000 1000)) reduces GC pauses

Configuration Management

Package Management Best Practices

Approach	Reliability	Setup Time	Maintenance Cost
Manual config	Low	High	Very High
use-package	High	Medium	Low
Doom Emacs	Very High	10 minutes	Very Low
Spacemacs	High	15 minutes	Low

Critical Decision Point: Custom configs fail frequently under deadline pressure. Pre-built frameworks solve 90% of configuration issues immediately.

Package Installation Failures

SSL/Certificate Issues:

(setq package-check-signature nil)
(setq gnutls-algorithm-priority "NORMAL:-VERS-TLS1.3")

Impact: Reduces security but enables immediate functionality. Fix certificates later.

Version Pinning (prevents surprise breakage):

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

Performance Optimization

Critical Performance Killers

Issue	Impact	Solution	Severity
Line numbers on huge files	Editor unusable	(setq display-line-numbers-type nil)	Critical
Auto-save every keystroke	Constant lag	(setq auto-save-timeout 300)	High
Company mode eager completion	Input lag	(setq company-idle-delay 0.5)	Medium
Git status in modeline	Destroys performance in large repos	(setq doom-modeline-vcs-max-length 12)	Critical

Native Compilation Requirements

• Emacs 28+: Native compilation provides significant speed improvements
• Large repositories: Git operations become bottleneck regardless of Emacs optimization

LSP Server Management

Common LSP Failures

1. 60% of issues: M-x eglot-reconnect resolves connection problems
2. Error diagnosis: Check *EGLOT* buffer for actual error messages
3. Process cleanup: pkill -f "language-server-name" kills crashed servers
4. Version conflicts: Old LSP servers break with new Emacs releases

Project Configuration

• .dir-locals.el: Project-specific LSP settings prevent global config pollution
• Server compatibility: Different Emacs versions require different LSP server versions

Environment-Specific Issues

Server vs Local Differences

Common failure modes:

• Different Emacs versions (27.1 vs 28.2+)
• Missing system dependencies
• GUI features in terminal-only environments

Version checking:

(when (version< emacs-version "27.1")
  (error "This config requires Emacs 27.1 or higher"))

PATH Configuration Issues

Diagnosis commands:

• M-x executable-find "git" - Verify tool availability
• C-h v exec-path - Check Emacs PATH vs shell PATH

Solution: Install exec-path-from-shell for GUI environments:

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

Production Debugging Workflow

Binary Search Configuration Debugging

1. Comment out bottom half of config
2. Restart Emacs
3. If broken: problem in top half. If working: problem in bottom half
4. Repeat until exact line identified

Alternative: Split config into multiple files, load incrementally

External Tool Dependencies

Tool	Check Command	Common Failure
Git	executable-find "git"	PATH issues
Spell checker	executable-find "aspell"	Missing package
PDF tools	executable-find "pdflatex"	LaTeX not installed

Nuclear Options (Last Resort)

Progressive Reset Procedures

1. Package reset: rm -rf ~/.emacs.d/elpa/ - Reinstall all packages
2. Custom settings: rm ~/.emacs.d/custom.el - Reset all customizations
3. Complete rebuild: Compile Emacs from source with exact feature requirements
4. Framework migration: Switch to Doom Emacs or Spacemacs for immediate functionality

Framework Decision Criteria

Use pre-built framework when:

• Under deadline pressure
• More than 2 hours spent debugging config issues
• Need immediate productivity over customization control

Critical Warnings

Production Environment Gotchas

• Terminal color limitations: Many themes break in terminal mode. Use terminal-specific themes or GUI Emacs
• Memory leaks: LSP mode with large projects, Helm with huge history, forgotten buffers cause RAM exhaustion
• Package conflicts: Loading order matters. Use use-package to manage dependencies automatically

Configuration Debt

• Custom configs: High maintenance cost, frequent breakage under pressure
• Package version drift: Unstable MELPA packages break without warning
• External tool assumptions: Configs often assume specific system dependencies

Resource Requirements

Time Investment Reality

• Custom config from scratch: 20-40 hours initial setup + ongoing maintenance
• Doom Emacs adoption: 10 minutes setup + 2-4 hours learning
• Debugging session: 30 minutes to 3 hours depending on issue complexity

Expertise Requirements

• Basic troubleshooting: Elisp reading ability
• Advanced debugging: Understanding of package loading, compilation, external tool integration
• Production deployment: System administration skills for dependency management

Decision Support Matrix

Scenario	Recommended Action	Time Cost	Success Rate
Deadline pressure + broken config	Switch to Doom Emacs	10 minutes	95%
Learning/exploration phase	Custom config with use-package	4-8 hours	70%
Production server deployment	Minimal config + essential packages	1-2 hours	85%
Team environment	Standardized framework (Doom/Spacemacs)	30 minutes	90%

Key insight: Pride in custom configuration is not worth missing deadlines. Productivity trumps customization when work needs completion.