Table of Contents

TexLive debugging

LaTeX compilation errors stop the compile and display a message. Read the .log file or terminal output for line numbers and error messages. Common errors and fixes:

Undefined control sequence — you used a command that doesn't exist. Check spelling (\textbf not \textbold), ensure the package providing the command is loaded (\usepackage{amsmath} for \text), and verify no typo in command name.

Missing packages — LaTeX can't find a package you tried to load. Install it: apt install texlive-latex-extra or texdoc packagename to check if it exists. Some packages are in separate distributions.

Mismatched braces or environments — you have { without closing } or \begin{...} without \end{...}. The error message points to the line where LaTeX gave up; the actual mismatch is often earlier. Count braces carefully.

\textbf{bold text}      % correct
\textbf{bold text       % missing }
\begin{center}
  Text
\end{center}            % correct
\begin{center}
  Text
\end{flushleft}         % wrong closing environment

Too many } — you closed braces more than you opened them. LaTeX attempts to continue but later errors cascade. Find and remove extra braces.

Missing $ inserted — you're in text mode but used math symbols or syntax. Wrap math in $...$:

\textbf{The equation E = mc^2}        % wrong: ^ is math syntax
\textbf{The equation $E = mc^2$}      % correct

Illegal unit of measure — you used a unit that LaTeX doesn't recognize. Valid units: cm, mm, in, pt, em, ex. \vspace{2cm} is correct; \vspace{2} is wrong (missing unit).

Package conflicts — two packages don't play well together. Error messages mention both packages. Usually, load packages in a specific order (most are compatible, but some have known conflicts). Read package documentation.

Font not found — (xelatex/lualatex) you specified a font that's not installed. Check the font name: fc-list lists available fonts. Install missing fonts via your package manager or system font manager.

Reference undefined — you used \ref{key} but \label{key} doesn't exist, or the label is in the wrong place. Compile twice to resolve references; on the first pass, LaTeX doesn't know label locations yet.

Citation undefined — similar to references: \cite{key} references a BibTeX entry that doesn't exist in your .bib file. Check the key spelling and ensure \bibliography{filename} is present.

File not found — LaTeX can't find an included file (\input{file} or \includegraphics{file}). Check the filename and path. Use relative paths (same directory as the .tex file) or absolute paths from the project root.

Emergency stop — LaTeX encountered a fatal error and gave up. This is rare; usually earlier errors are more informative.

Debugging strategies:

  1. Read the .log file, not just terminal output (more detailed).
  2. Use \listfiles in the preamble to log all loaded files; useful for package version issues.
  3. Comment out suspicious blocks and recompile to narrow down the problem.
  4. Ensure packages are loaded in the right order (generally top-level packages first, styling packages last).
  5. Test with a minimal document to isolate the issue from content.
  6. Run texhash if you installed custom packages and LaTeX still can't find them.

Warnings vs errors — LaTeX continues compiling after warnings (usually safe but may produce unexpected output). Errors stop compilation. Address errors first, then warnings.