Site Tools


wiki:texlive-debugging

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 `$…$`: ```latex \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.

wiki/texlive-debugging.md · Last modified: by 127.0.0.1