spb/llm-api-toolkits

1# Costly errors and their fixes23`node scripts/latex.mjs explain "<message>"` matches a message against a table of known patterns.4This page gives the longer story for the ones that waste the most time. Where a behaviour depends5on package versions, it says so: check against your own log.67## Package order: babel, hyperref, cleveref89| Symptom | Cause | Fix |10|---|---|---|11| `\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 |12| Links from `\cref` go to the wrong place, or cleveref warns about hyperref | cleveref loaded before hyperref | Order: babel → … → hyperref → cleveref. cleveref is last |13| `Option clash for package …` | A class or another package already loaded it with other options | `\PassOptionsToPackage{opts}{pkg}` before `\documentclass` |14| `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 |15| Errors with `:` or `;` inside TikZ code in a French document | Same active characters | `\usetikzlibrary{babel}` |1617General rule: packages that redefine referencing (hyperref, then cleveref) go at the end of the18preamble, and the few that must follow hyperref say so in their documentation.1920## Biber against BibTeX2122Two bibliography systems exist and their auxiliary files are incompatible.2324| The document has | Backend | The build directory gets |25|---|---|---|26| `\bibliographystyle{…}` + `\bibliography{refs}` (plain BibTeX, natbib) | `bibtex` | `.bbl`, `.blg` |27| `\usepackage{biblatex}` + `\addbibresource{refs.bib}` | `biber` (default) | `.bcf`, `.bbl`, `.blg` |28| `\usepackage[backend=bibtex]{biblatex}` | `bibtex` | `.bbl`, `.blg` |2930| Symptom | Cause | Fix |31|---|---|---|32| 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 |33| `I found no \citation commands` / `no \bibdata command` in the `.blg` | BibTeX run on a biblatex/Biber document | Same |34| Errors inside the `.bbl` right after switching backend | A `.bbl` written by the other tool is still there | Build from scratch (`compile --clean`) |35| Biber stops with a control-file version error | Biber and biblatex come from different releases | Update both together (`tlmgr update biber biblatex`) |36| `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 |3738`bib` reports the expected backend, the one that ran, and the mismatch.3940## Fonts under XeLaTeX and LuaLaTeX4142| Symptom | Cause | Fix |43|---|---|---|44| `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=` |45| fontspec fails at load time | Compiled with pdfLaTeX | `--engine xelatex` or `lualatex` |46| 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 |47| Odd output after adding fontspec | `inputenc` / `fontenc` left in the preamble | Remove both under XeLaTeX / LuaLaTeX |48| Document compiles on one machine only | System fonts differ | Ship the font files with the project and load them by path |4950## Encoding (pdfLaTeX)5152| Symptom | Cause | Fix |53|---|---|---|54| `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 |55| `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 |56| `Missing \begin{document}` on line 1 | A byte-order mark or stray characters before `\documentclass` | Save without BOM |57| Accented words not hyphenated, copy-paste from the PDF gives odd characters | OT1 font encoding | `\usepackage[T1]{fontenc}` |58| 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) |5960## pgfplots and TikZ6162| Symptom | Cause | Fix |63|---|---|---|64| `running in backwards compatibility mode` on every build | No compatibility level set | `\pgfplotsset{compat=1.18}` (or the version you have) in the preamble |65| `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 |66| 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 |67| Builds that ask for shell escape | `external` library, gnuplot calls | Generate those figures separately; this tool never enables shell escape |6869## Floats, labels and numbering7071| Symptom | Cause | Fix |72|---|---|---|73| "Figure 2" in the text points at the section number | `\label` placed before `\caption` | `\caption{…}\label{…}`, in that order |74| `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` |75| `Too many unprocessed floats` | Floats cannot be placed | `[htbp]`, `\clearpage`, or `\FloatBarrier` (placeins) |76| `Label … multiply defined` | Copy-pasted float or section | `refs` gives both locations |7778## Code listings7980`minted` runs an external program for highlighting and therefore needs some form of shell escape,81which this tool never grants. Either generate the highlighted output once on a trusted machine82and compile from that cache (see the minted manual for the option matching your version), or use83`listings`, which is pure TeX.8485## Reading a log quickly8687- The **first** error matters; later ones mostly follow from it.88- The line starting with `l.<number>` shows the input line and where TeX stopped reading.89- In `file:line:error` style (used by this tool) each error starts with `./file.tex:12:`.90- `Emergency stop` and `Fatal error occurred` are consequences, not causes.91