Troubleshooting Common Latex Errors And Warnings
Missing Packages
One of the most common LaTeX errors is the missing package error. This occurs when you try to use a command from a package that is not installed or imported in your preamble. For example, you may get errors like:
! LaTeX Error: File `geometry.sty' not found.
Or:
! Undefined control sequence. l.23 \begin{table} ?
To resolve missing package errors:
- Install any missing packages in your LaTeX distribution
- Add \usepackage{missing-package} to your preamble
- Or comment out the offending code that relies on the missing package
Examples of Missing Packages
Some common packages that often generate missing package errors include:
- geometry - Handles page margins and dimensions
- graphicx - Enables importing images and figures
- amsmath - Extends math capabilities in LaTeX
- fancyhdr - Customizes headers and footers
- hyperref - Adds hyperlinks and PDF properties
To install any of these missing packages (using TexLive in Linux for this example):
sudo tlmgr install geometry
Undefined Control Sequences
Undefined control sequence errors indicate you are trying to use a command that LaTeX does not recognize. For example:
! Undefined control sequence. l.26 \someunknowncommand ?
This often occurs when:
- Typos in command names
- Forgetting to import the package that defines the command
- Using outdated package documentation
To troubleshoot undefined control sequences:
- Check the spelling of unrecognized commands
- Verify you imported the right packages
- Compare with updated package documentation
- Search LaTeX questions forums when stuck
Common Undefined Commands
Some frequent sources of undefined command errors:
- \renewcommand - Defined in the etoolbox package
- \textbackslash - Need the escapesym package
- \href - In the hyperref package
- \SI - SIunits package required
Fixing these requires adding the associated \usepackage{package} line.
Missing \begin{document}
Nearly all LaTeX documents require the \begin{document} and \end{document} delimiters to denote the main content body. Forgetting \begin{document} generates errors like:
! LaTeX Error: Missing \begin{document}. See the LaTeX manual or LaTeX Companion for explanation. Type Hfor immediate help. ... l.15 \section{Introduction} ?
A minimal LaTeX document structure looks like:
\documentclass{article} \begin{document} Hello World! \end{document}
The \documentclass declaration specifies the document class. Text, commands, and markup come after \begin{document}. So verify \begin{document} exists and text is not before it.
File Not Found
The file not found or cannot find file errors appear when importing files like images. For example:
! LaTeX Error: File `missing.png' not found.
Some ways these file issues occur:
- Misspelled file names
- Incorrect relative file paths
- Access permissions errors
- Moving build files across systems
Solutions include:
- Double check file names match exactly
- Use relative paths from the main .tex file location
- Specify full absolute file paths instead
- Make files readable on relevant systems
Examples of File Paths
Assuming a main .tex file in:
/home/user/doc/mypaper.tex
Relative image file paths could be:
\includegraphics{figures/diagram.png} (from same directory) \includegraphics{../figures/diagram.png} (traversing up one directory)
While absolute image file paths look like:
\includegraphics{/home/user/doc/figures/diagram.png}
Incompatible Package Versions
If multiple LaTeX packages rely on conflicting versions of the same package, compilation errors can occur. For example:
("C:\Program Files\MiKTeX 2.9\tex\latex\titlesec\titlesec.sty" ("C:\Program Files\MiKTeX 2.9\tex\latex\tools\xspace.sty")) ! LaTeX Error: Command \titlespacing already defined. Or name \end... illegal, see p.192 of the manual. See the LaTeX manual or LaTeX Companion for explanation. Type Hfor immediate help. ... l.190 \newcommand {\titlespacing}[5]{% ?
This happens when an older package version expects an older command definition. To address it:
- Update all packages to latest versions
- Add \usepackage[version-num]{package} to lock to known good versions
- \RequirePackage[version-num]{package} forces specific versions
After updating packages, be wary of new errors due to API changes in packages.
Examples of Version Fixes
\usepackage[version=4]{mhchem} % Lock mhchem v4 \RequirePackage[2017/06/05]{latexrelease} % latexrelease date
Exceeding Compilation Memory
Large, complex LaTeX documents can sometimes exceed the memory limits during compilation. For example:
("C:\FilesLocation\MyDoc.aux") ! TeX capacity exceeded, sorry [main memory size=5000000]. \end #1->\csname end#1 \endcsname \@checkend {#1}\expandafter \end \def \csname #1... l.183 \EndEnumerate ? ! Emergency stop. \end #1->\csname end#1 \endcsname \@checkend {#1} EndEnumerate --> EndEnumerate ! ==> Fatal error occurred, no output PDF file produced! Transcript written on MyDoc.log.
Common causes include:
- Too many high resolution images
- Overly complex tables or math equations
- Recursive functions or calculations
- Bibliographies with thousands of references
To reduce memory issues:
- Simplify document structure when possible
- Lower resolution of imported graphics
- Split across multiple subfiles using \input or \include
- Use \nocite{*} for large bibliography case
Fixing Common LaTeX Warnings
In addition to fatal LaTeX errors that prevent output, warnings alert issues that may need fixing:
LaTeX Warning: Citation `grover1998' on page 2 undefined on input line 378. LaTeX Warning: Font shape `OT1/cmr/bx/it' in size <4> not available (Font) size <5> substituted on input line 98. LaTeX Warning: Reference `fig:process' on page 4 undefined on input line 343.
Frequent LaTeX warnings involve:
- Broken citations or references
- Missing fonts and font packages
- Undefined labels and markers
Addressing warnings prevents future confusion and ensures a clean build log. Such as:
- Fixing typos in citation keys and \refs
- Importing font packages like mathpazo
- Adding missing labels and markers
Examples of Warning Resolution
To address common LaTeX warnings:
\usepackage[T1]{fontenc} % Fix missing font warnings \bibliography{refs} % Defines citation reference files \nocite{*} \label{fig:process} % Label markers before references Figure \ref{fig:process} diagram...
Debugging the LaTeX Build Process
More difficult LaTeX issues require methodically debugging the build process. Useful techniques involve:
- Reviewing the .log for first LaTeX error message
- Using \errorcontextlines to output nearby context
- Temporarily commenting out recent chunk of document changes
- Parsing remaining text with tiered \include or \input files
- Running LaTeX multiple times to isolate nested issues
Often the root cause surfaces through search engines or LaTeX help sites when simple fixes are not evident.
Tools to Assist Debugging
Handy LaTeX commands when debugging:
- \errorcontextlines shows number lines around issue
- \listfiles logs all imported files
- \layout views document box structure
- \show outputs macro code
- \includeonly{chap1} only compiles given file
Enclose suspect content in:
\begin{comment} ... \end{comment}
Or conditionally include using:
\ifdef{\flagA} \input{chloride} \endif
Preventing Future Errors
While debugging individual LaTeX issues leads to solutions, additional work up front avoids repeated problems. Wise practices like:
- Keeping master documents lean
- Using version control systems
- Breaking documents into modules
- Commenting revisions
- Learning from others' clean .tex style
Greatly ease long term maintainability.
Recommendations for Robust Documents
Specific recommendations to prevent future LaTeX errors:
- Separate content across master .tex and \included files
- Use Git or SVN to track incremental changes
- Package project as a .texmf directory when possible
- Reference style guidelines like l2tabu with custom commands
- Add keywords indicating origins of imported content
Investing in strong framework and reusing prior solutions produces more robust documents.