Ivan's wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
# 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.

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