debug — LaTeX log triage

Always run latex with these flags

latexmk -interaction=nonstopmode -file-line-error -halt-on-error <flag> <main>.tex

-file-line-error rewrites errors as path/file.tex:NNN: <msg> — far easier to parse than the default style. nonstopmode prevents the ? prompt from blocking. -halt-on-error stops on the first error so the log is clean.

If max_print_line isn't already set, add env TEXMFOUTPUT=. max_print_line=10000 latexmk ... to prevent 79-char wrapping. (Some installs set it via texmf.cnf.)

Source: TeX FAQ (https://texfaq.org); LaTeX2e error semantics (https://latexref.xyz/).

Error taxonomy and fixes

Run scripts/parse_log.py <main>.log. It returns the first ! error plus surrounding context. Match against this table:

Undefined control sequence

! Undefined control sequence.
l.NNN \foo

Cause: typo, missing package, wrong engine. Procedure:

1. Search the document for \foo.
2. Run texdoc -l \foo or search CTAN for "<foo>" — what package defines it?
3. If the package is missing from the preamble: add \usepackage{<pkg>}.
4. If the package is present and the engine is pdflatex but the macro is lualatex/xelatex-specific (e.g. \setmainfont requires fontspec): switch engine. See /academic-latex:compile engine detection.
5. If unsure which package owns the command, delegate to /academic-latex:docs-lookup with the question.

Missing $ inserted

! Missing $ inserted.

Cause: math-mode character (_, ^, \alpha) in text mode, OR blank line inside $...$/\(...\)/equation. Fix: wrap the offending fragment in math mode ($..$), or escape _ as \_, or remove the blank line. Look at l.NNN: the line just before is the source.

File '<x>.sty' / '<x>.cls' / '<x>.bbx' not found

Cause: package not installed. Fix (TeX Live): tlmgr install <x>. MiKTeX: mpm --install=<x> or rely on auto-install. Mac (TeX Live via MacTeX): sudo tlmgr install <x>. Confirm with kpsewhich <x>.sty.

Package <name> Error

Cause: package-specific. Match on <name>. Procedure:

1. Read the full message — most packages give a precise reason.
2. Open the package PDF: texdoc <name>. Or delegate to /academic-latex:docs-lookup with the verbatim error string.
3. Apply the fix per the package's documented remediation.

Common cases:

• Package biblatex Error: Incompatible package 'natbib'. — Don't load both. Pick one. See /academic-latex:bibliography.
• Package fontspec Error: The fontspec package requires either XeTeX or LuaTeX. — Switch engine to xelatex/lualatex.
• Package polyglossia Error: ... — See /academic-latex:multilingual.

Runaway argument

Runaway argument?
{...
! Paragraph ended before \foo was complete.

Cause: unmatched { or }, or \par (blank line) inside a non-long argument. Fix: find the unbalanced brace. The line cited is where TeX gave up, not the cause; scan upward.

Citation 'X' undefined

Cause: .bbl not produced or out of date. Fix: rerun bib backend (biber <main> or bibtex <main>), then 2 more pdflatex passes. With latexmk, this is automatic — confirm .bcf (biber) or correct \bibdata (bibtex) exists.

Reference 'X' undefined / 'X' on page Y undefined

Cause: .aux out of date. Fix: rerun pdflatex. With latexmk, automatic.

Overfull / Underfull \hbox

Cause: layout overflow (overfull = content too wide; underfull = stretched too far). Procedure: these are warnings, not fatal. Quote the line in the log: Overfull \hbox (15.2pt too wide) in paragraph at lines 10--12. Possible fixes:

1. Add \usepackage{microtype} if not loaded — eliminates many cases.
2. Insert \sloppy for one paragraph (or \begin{sloppypar}...\end{sloppypar}).
3. Hyphenate the offending long word: hy\-phen\-ate.
4. Rephrase. Sometimes the cleanest fix.

Source: microtype PDF at https://www.tug.org/docs/latex/microtype/microtype.pdf.

Other patterns

• ! TeX capacity exceeded — recursive macro or pathological input. Often a missing } causing TeX to read forever.
• ! I can't find file '<x>' — \input{<x>} or \include{<x>} with wrong path; check working directory. Forward slashes only.
• ! LaTeX Error: \begin{<env>} on input line N ended by \end{<other>}. — environment mismatch; find the unmatched \end.

When you don't know

If the error is package-specific and the fix isn't obvious:

1. Quote the error verbatim.
2. Invoke /academic-latex:docs-lookup with: "Package <name>: what does error <message> mean and how is it fixed?".
3. Apply the documented remediation. Cite the source URL when proposing the fix.

Never invent a fix. Wrong fixes for LaTeX errors are time-expensive — docs-lookup cost is much lower than a misled debugging loop.

Output format

Error class: <one of: undefined-cs | missing-package | missing-file | math-mode | runaway | package-error | undefined-ref | undefined-cite | overfull | underfull | other>
Source location: <file>:<line>
Verbatim error: <the ! line and 1-2 lines after>
Likely cause: <one sentence>
Proposed fix: <specific change(s) to source or commands to run>
Confidence: high|medium|low (low → consult docs-lookup before applying)

Last verified

2026-05-09 — log format from TeX FAQ (https://texfaq.org); error taxonomy from latexref.xyz and Overleaf documentation hub.