# Costly errors and their fixes

node scripts/latex.mjs explain "<message>" matches a message against a table of known patterns. This page gives the longer story for the ones that waste the most time. Where a behaviour depends on package versions, it says so: check against your own log.

# Package order: babel, hyperref, cleveref

Symptom	Cause	Fix
`\cref` prints `??` or English names in a French document	cleveref loaded before babel knew the language, or without the language option	Give the language as a class option (`\documentclass[french]{article}`) so every package sees it, and load cleveref after babel
Links from `\cref` go to the wrong place, or cleveref warns about hyperref	cleveref loaded before hyperref	Order: babel → … → hyperref → cleveref. cleveref is last
`Option clash for package …`	A class or another package already loaded it with other options	`\PassOptionsToPackage{opts}{pkg}` before `\documentclass`
`Missing \endcsname inserted` at a `\cref{fig:a}`, while `\ref{fig:a}` works	babel-french under pdfLaTeX makes `:` `;` `!` `?` active, and cleveref cannot read a label that contains one. Reproduced with TeX Live 2026	Any one of: label names without a colon (`fig-a`); compile with LuaLaTeX (no active characters there); `\shorthandoff{:;!?}` after `\begin{document}`, which also turns off the automatic French spacing before those marks. Adding the `french` option to cleveref does not fix it
Errors with `:` or `;` inside TikZ code in a French document	Same active characters	`\usetikzlibrary{babel}`

General rule: packages that redefine referencing (hyperref, then cleveref) go at the end of the preamble, and the few that must follow hyperref say so in their documentation.

# Biber against BibTeX

Two bibliography systems exist and their auxiliary files are incompatible.

The document has	Backend	The build directory gets
`\bibliographystyle{…}` + `\bibliography{refs}` (plain BibTeX, natbib)	`bibtex`	`.bbl`, `.blg`
`\usepackage{biblatex}` + `\addbibresource{refs.bib}`	`biber` (default)	`.bcf`, `.bbl`, `.blg`
`\usepackage[backend=bibtex]{biblatex}`	`bibtex`	`.bbl`, `.blg`

Symptom	Cause	Fix
Every citation undefined; log says `Please (re)run Biber`	The editor ran BibTeX on a biblatex document, or ran nothing	Run Biber. latexmk chooses correctly by itself
`I found no \citation commands` / `no \bibdata command` in the `.blg`	BibTeX run on a biblatex/Biber document	Same
Errors inside the `.bbl` right after switching backend	A `.bbl` written by the other tool is still there	Build from scratch (`compile --clean`)
Biber stops with a control-file version error	Biber and biblatex come from different releases	Update both together (`tlmgr update biber biblatex`)
`I couldn't open database file` / `Cannot find 'x.bib'`	Wrong path, or the `.bib` is not where the tool runs	Path relative to the main file; with biblatex include the `.bib` extension

bib reports the expected backend, the one that ran, and the mismatch.

# Fonts under XeLaTeX and LuaLaTeX

Symptom	Cause	Fix
`fontspec error: "font-not-found"`	The named font is not installed on this machine	Use an installed family name (`fc-list : family` lists them) or load the font by file name with `Path=`
fontspec fails at load time	Compiled with pdfLaTeX	`--engine xelatex` or `lualatex`
Accents or symbols missing in the PDF, no error	The font lacks the glyph; TeX only logs `Missing character: There is no … in font …`	`log` lists them under `missing_characters`. Change font or add a fallback
Odd output after adding fontspec	`inputenc` / `fontenc` left in the preamble	Remove both under XeLaTeX / LuaLaTeX
Document compiles on one machine only	System fonts differ	Ship the font files with the project and load them by path

# Encoding (pdfLaTeX)

Symptom	Cause	Fix
`Invalid UTF-8 byte`	The file is saved in Latin-1 or Windows-1252	Re-save as UTF-8; UTF-8 has been LaTeX's default input encoding since 2018
`Unicode character … not set up for use with LaTeX`	A character with no definition (a typographic space, an emoji, a Greek letter in text)	Replace it, define it with `\DeclareUnicodeCharacter`, or change engine
`Missing \begin{document}` on line 1	A byte-order mark or stray characters before `\documentclass`	Save without BOM
Accented words not hyphenated, copy-paste from the PDF gives odd characters	OT1 font encoding	`\usepackage[T1]{fontenc}`
Odd characters in the bibliography only	The `.bib` file has another encoding than the document	Convert the `.bib` to UTF-8 (Biber expects UTF-8 by default)

# pgfplots and TikZ

Symptom	Cause	Fix
`running in backwards compatibility mode` on every build	No compatibility level set	`\pgfplotsset{compat=1.18}` (or the version you have) in the preamble
`Dimension too large`	Values beyond TeX's range, often dates or large counts on an axis	Rescale the data, use a log axis, or a restricted domain
Very slow builds, `TeX capacity exceeded`	Plots with tens of thousands of points	Thin the data before plotting, or include the figure as a PDF made elsewhere
Builds that ask for shell escape	`external` library, gnuplot calls	Generate those figures separately; this tool never enables shell escape

# Floats, labels and numbering

Symptom	Cause	Fix
"Figure 2" in the text points at the section number	`\label` placed before `\caption`	`\caption{…}\label{…}`, in that order
`Label(s) may have changed` forever	Numbers oscillate between runs	Usually a `\pageref` or a float at a page boundary: move it or add `\clearpage`
`Too many unprocessed floats`	Floats cannot be placed	`[htbp]`, `\clearpage`, or `\FloatBarrier` (placeins)
`Label … multiply defined`	Copy-pasted float or section	`refs` gives both locations

# Code listings

minted runs an external program for highlighting and therefore needs some form of shell escape, which this tool never grants. Either generate the highlighted output once on a trusted machine and compile from that cache (see the minted manual for the option matching your version), or use listings, which is pure TeX.

# Reading a log quickly

The first error matters; later ones mostly follow from it.
The line starting with l.<number> shows the input line and where TeX stopped reading.
In file:line:error style (used by this tool) each error starts with ./file.tex:12:.
Emergency stop and Fatal error occurred are consequences, not causes.

spb llm-api-toolkits