Introduction
Every LaTeX user encounters errors. Understanding how to read error messages, interpret log files, and apply systematic debugging approaches transforms frustrating problems into solvable challenges.
This guide provides systematic debugging techniques that work for any LaTeX problem.
Reading Error Messages
Error Message Format
! Package amsmath Error: Multiple \tag.
l.23 \tag{first}
?
Components:
!: Error indicatorPackage amsmath Error: Error sourceMultiple \tag: Error typel.23: Line number\tag{first}: Problematic code
Warning Messages
LaTeX Warning: Reference `fig:missing' on page 1 undefined
Warnings don’t stop compilation but indicate problems.
Log File Analysis
# Find all errors
grep "^!" document.log
# Find warnings
grep "Warning" document.log
# Find overfull boxes
grep "Overfull" document.log
Common Error Categories
File Not Found
! LaTeX Error: File `mypackage.sty' not found.
Solutions:
- Install package:
tlmgr install packagename - Check filename spelling
- Verify working directory
Encoding Errors
! Package inputenc Error: Unicode character (U+00A9)
Solutions:
- Use
\usepackage[utf8]{inputenc} - Use XeLaTeX/LuaLaTeX for Unicode
Math Mode Errors
! Missing $ inserted.
Causes:
- Special characters in text mode
- Missing math delimiters
Compilation Errors
pdflatex vs latex
# For PDF output (most common)
pdflatex document.tex
# For DVI output
latex document.tex
# For XeLaTeX (Unicode)
xelatex document.tex
# For LuaLaTeX (Lua)
lualatex document.tex
Missing Auxiliary Files
# Complete build sequence
pdflatex document
bibtex document # or biber document
makeindex document
pdflatex document
pdflatex document
Build Failures
% Use nonstopmode to continue on errors
pdflatex -interaction=nonstopmode document.tex
Package Errors
Package Conflicts
! Package conflict with hyperref and cleveref
Solutions:
- Load packages in correct order
- Use
\AfterPackagecommands
Option Conflicts
! Package keyval Error: xxx undefined.
Solutions:
- Check package options
- Update packages
Version Issues
! Package too old
Solutions:
tlmgr update --self
tlmgr update packagename
Bibliography Errors
Citation Not Found
! Citation `smith2024' undefined.
Causes:
- BibTeX/Biber not run
- Citation key mismatch
Bibliography Not Generated
! Package biblatex Error: Biber reported errors.
Solutions:
biber document
pdflatex document
pdflatex document
Encoding in BibTeX
% Ensure UTF-8 in .bib file
@article{key,
author = {Schr{\"o}der},
title = {Analysis},
}
Figure and Table Errors
Figure Not Found
! LaTeX Error: File `figure.pdf' not found.
Solutions:
\graphicspath{{./figures/}}
\usepackage{graphicx}
Float Too Large
! LaTeX Error: Too many unprocessed floats
Solutions:
\clearpage
\FloatBarrier
Math Errors
Math Font Issues
! Font \cmex10 not loadable
Solutions:
\usepackage{amsmath}
\usepackage[T1]{fontenc}
Equation Numbering
! Counter too large.
Solutions:
\numberwithin{equation}{section}
Debugging Techniques
Minimal Example
% Create minimal document showing the error
\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage{amsmath}
\begin{document}
% Minimal example showing the problem
$a = b + c$
\end{document}
Draft Mode
\documentclass[draft]{article}
% Shows overfull boxes
% Speeds compilation
Show Keys
\usepackage{showkeys}
% Shows labels in margin
Tracing
\tracingonline=1
\show\command
\meaning\command
Error Prevention
Best Practices
- Compile frequently
- Use version control
- Keep backups
- Test new packages in isolation
Automation
% latexmkrc for automatic builds
$pdflatex = 'pdflatex -interaction=nonstopmode %S';
$bibtex = 'biber %B';
$makeindex = 'makeindex %S -s gind.ist';
Troubleshooting Checklist
- Check error message line number
- Verify all packages loaded
- Ensure compilation sequence correct
- Check file paths and names
- Review log file warnings
- Try minimal example
- Update packages
Comments