LaTeX & TeX Error Reference Catalog
This catalog documents common LaTeX and TeX compilation errors, their root causes, canonical reference links, and how latex_it identifies, diagnoses, and provides remediation hints for each issue.
1. Classification & Architecture
Errors during compilation originate in one of three layers:
- TeX Engine Primitives: Generated by the TeX core parser (
pdftex,xetex,luatex). In-file-line-errormode, these appear as<file>:<line>: <message>.. - LaTeX2e Kernel Errors: Emitted via
\@latex@error(e.g. environment mismatches, missing items). These appear as<file>:<line>: LaTeX Error: <message>.. - Package-Specific Errors: Emitted via
\PackageError{<pkg>}{...}(e.g.amsmath,xcolor,hyperref,biblatex,tikz).
2. latex_it Diagnostic Tiers
| Handling Level | Description |
|---|---|
Pre-Flight |
Detected statically before compilation via LaTeXBraceChecker (e.g. unclosed braces, inverted labels, and environment mismatches). |
Catalog Hint |
Classified via LaTeXErrorCatalog, which extracts offending tokens (commands, environments, filenames) and prints an inline actionable remediation hint (▸ Hint:). Full boxed explanations (Why: / Fix:) are rendered on demand with --explain. |
Standard |
Captured via -file-line-error logging with source snippet and line attribution. |
Fatal |
Critical engine termination (Emergency stop); surfaces the primary fault line and points to the raw transcript. |
3. Master Error Index (55 Errors)
| # | Error Message / Pattern | Layer | Cause & Summary | Support | Reproducer & Details |
|---|---|---|---|---|---|
| 01 | Misplaced alignment tab character & |
TeX Primitive | & used outside tabular, matrix, or align (e.g. inside equation* or unescaped in prose). |
Catalog Hint | 01_misplaced_alignment_tab |
| 02 | Undefined control sequence |
TeX Primitive | Misspelled command or macro requiring an unloaded package. Extracts command name. | Catalog Hint | 02_undefined_control_sequence |
| 03 | Something's wrong--perhaps a missing \item |
LaTeX Kernel | Text inside list environment (itemize, enumerate) before an \item. |
Catalog Hint | 03_missing_item |
| 04 | Missing $ inserted |
TeX Primitive | Math-only token (e.g. _, ^, \alpha) used in text mode. |
Catalog Hint | 04_missing_dollar |
| 05 | Too many }'s / Extra closing brace '}' |
TeX Primitive | An unmatched closing brace } encountered with no corresponding open brace. |
Pre-Flight / Hint | 05_extra_closing_brace |
| 06 | Paragraph ended before \foo was complete / Runaway argument? |
TeX Primitive | Blank line inside argument of non-\long macro or unclosed brace across paragraph. |
Catalog Hint | 06_paragraph_ended_before_complete |
| 07 | LaTeX Error: Environment \foo undefined |
LaTeX Kernel | \begin{foo} called for an environment not declared in class or loaded packages. |
Catalog Hint | 07_environment_undefined |
| 08 | LaTeX Error: There's no line here to end |
LaTeX Kernel | \\ or \newline called at the start of a paragraph or empty block where no line exists. |
Catalog Hint | 08_no_line_here_to_end |
| 09 | LaTeX Error: File 'foo' not found |
LaTeX Kernel | Missing package or non-existent file referenced via \usepackage or \input. |
Catalog Hint | 09_file_not_found |
| 10 | LaTeX Error: Command \foo already defined |
LaTeX Kernel | \newcommand{\foo} used when \foo already exists. Solution: use \renewcommand. |
Catalog Hint | 10_command_already_defined |
| 11 | Extra alignment tab has been changed to \cr |
TeX Primitive | Row contains more & columns than declared in tabular column specification. |
Catalog Hint | 11_extra_alignment_tab |
| 12 | Missing number, treated as zero |
TeX Primitive | Expected numeric constant or dimension value but found text or unit without number. | Catalog Hint | 12_missing_number_treated_as_zero |
| 13 | Illegal unit of measure (pt inserted) |
TeX Primitive | Dimension had a number but omitted the unit of measurement (pt, cm, mm, in). | Catalog Hint | 13_illegal_unit_of_measure |
| 14 | Double subscript |
TeX Primitive | Multiple _ operators directly applied to the same base (e.g. x_a_b instead of x_{a_b}). |
Catalog Hint | 14_double_subscript |
| 15 | Double superscript |
TeX Primitive | Multiple ^ operators directly applied to the same base (e.g. x^a^b instead of x^{a^b}). |
Catalog Hint | 15_double_superscript |
| 16 | LaTeX Error: Option clash for package foo |
LaTeX Kernel | Package loaded multiple times with mutually conflicting options. | Catalog Hint | 16_option_clash_for_package |
| 17 | LaTeX Error: Lonely \item--perhaps a missing list environment |
LaTeX Kernel | \item command used outside any enclosing list environment (itemize, enumerate). |
Catalog Hint | 17_lonely_item |
| 18 | LaTeX Error: Cannot determine size of graphic |
LaTeX Kernel | Graphics loader cannot parse image header or bounding box dimensions. | Catalog Hint | 18_cannot_determine_size_of_graphic |
| 19 | LaTeX Error: Not in outer par mode |
LaTeX Kernel | Float (figure, table) placed inside restricted box (\mbox) or table cell. |
Catalog Hint | 19_not_in_outer_par_mode |
| 20 | Missing delimiter (. inserted) |
TeX Primitive | \left or \right command without delimiter; use . for empty/dummy delimiter. |
Catalog Hint | 20_missing_delimiter |
| 21 | LaTeX Error: Can be used only in preamble |
LaTeX Kernel | Preamble macro (e.g. \usepackage, \documentclass) executed after \begin{document}. |
Catalog Hint | 21_only_in_preamble |
| 22 | Extra \right |
TeX Primitive | Closing \right delimiter without a matching \left opening delimiter. |
Catalog Hint | 22_extra_right |
| 23 | LaTeX Error: Missing \begin{document} |
LaTeX Kernel | Printable text or typesetting commands encountered before \begin{document}. |
Catalog Hint | 23_missing_begin_document |
| 24 | Dimension too large |
TeX Primitive | Length or coordinate calculation exceeded TeX limit (~16383.99pt / 5.75m). | Catalog Hint | 24_dimension_too_large |
| 25 | Misplaced \noalign / Misplaced \omit |
TeX Primitive | \hline or \cline placed after table cell content instead of right after \\. |
Catalog Hint | 25_misplaced_noalign |
| 26 | LaTeX Error: Bad math environment delimiter |
LaTeX Kernel | Opening math delimiter closed with mismatched delimiter (e.g. \( ... \]). |
Catalog Hint | 26_bad_math_environment_delimiter |
| 27 | LaTeX Error: Counter too large |
LaTeX Kernel | Counter representation (e.g. \fnsymbol) exceeded fixed symbol pool (9 max). |
Catalog Hint | 27_counter_too_large |
| 28 | Package amsmath Error: Multiple \tag |
Package | Multiple \tag{...} labels assigned to a single equation line. |
Catalog Hint | 28_amsmath_multiple_tag |
| 29 | Package xcolor Error: Undefined color |
Package | Requested color name not defined or loaded via \usepackage[dvipsnames]{xcolor}. |
Catalog Hint | 29_undefined_color |
| 30 | LaTeX Error: \begin{foo} ended by \end{bar} |
LaTeX Kernel | Mismatched environment tags (e.g. \begin{itemize} closed by \end{enumerate}). |
Pre-Flight / Hint | 30_mismatched_environment |
| 31 | Missing } inserted |
TeX Primitive | TeX reached EOF or end of group while macro argument or math construct was missing closing }. |
Catalog Hint | 31_missing_closing_brace |
| 32 | Missing \endcsname inserted |
TeX Primitive | Macro inside \csname ... \endcsname expanded into unexpandable or invalid control sequence. |
Catalog Hint | 32_missing_endcsname |
| 33 | You can't use '\hrule' here |
TeX Primitive | Vertical rule \hrule used in horizontal/math mode. Solution: use \rule or switch to vertical mode. |
Catalog Hint | 33_cant_use_hrule_here |
| 34 | You can't use '\spacefactor' in math mode |
TeX Primitive | Spacefactor macro or punctuation modifier invoked in math mode instead of text mode. | Catalog Hint | 34_cant_use_spacefactor |
| 35 | Illegal parameter number in definition of \foo |
TeX Primitive | Referenced #n exceeds number of declared macro parameters, or unescaped # inside macro body. |
Catalog Hint | 35_illegal_parameter_number |
| 36 | LaTeX Error: Two \documentclass commands |
LaTeX Kernel | Document preamble contains multiple \documentclass declarations. |
Catalog Hint | 36_two_documentclass_commands |
| 37 | LaTeX Error: \verb illegal in command argument |
LaTeX Kernel | Verbatim macro \verb passed inside another command’s argument; use \texttt or \cprotect. |
Catalog Hint | 37_verb_illegal_in_argument |
| 38 | LaTeX Error: \caption outside float |
LaTeX Kernel | \caption used outside floating environment (figure, table); use \captionof from caption package. |
Catalog Hint | 38_caption_outside_float |
| 39 | Use of \foo doesn't match its definition |
TeX Primitive | Macro with delimited argument syntax called with missing or mismatched delimiter tokens. | Catalog Hint | 39_use_of_doesnt_match_definition |
| 40 | Ambiguous; you need another { and } |
TeX Primitive | TeX \over or \atop used multiple times in same formula without grouping braces { ... }. |
Catalog Hint | 40_ambiguous_math_fractions |
| 41 | You can't use '\eqno' in math mode |
TeX Primitive | Display-math tag command \eqno used in inline math $ ... $; switch to \[ ... \] or equation. |
Catalog Hint | 41_cant_use_eqno_in_math |
| 42 | Package babel Error: Unknown language 'foo' |
Package | Specified babel language option not supported or hyphenation patterns not installed. | Catalog Hint | 42_package_babel_unknown_language |
| 43 | Bad register code |
TeX Primitive | Allocation index out of range for count, dimen, or box register (valid 0–255 in TeX, 0–65535 in e-TeX). | Catalog Hint | 43_bad_register_code |
| 44 | LaTeX Error: \include cannot be nested |
LaTeX Kernel | An \include{...} file attempted to call \include{...}; use \input{...} for nested files. |
Catalog Hint | 44_nested_include |
| 45 | LaTeX Error: No counter 'foo' defined |
LaTeX Kernel | Manipulating or printing counter \foo that was never created via \newcounter{foo}. |
Catalog Hint | 45_no_counter_defined |
| 46 | LaTeX Error: Command \foo undefined |
LaTeX Kernel | \renewcommand{\foo} called for a macro name that does not exist; use \newcommand. |
Catalog Hint | 46_command_undefined |
| 47 | File ended while scanning use of \foo |
TeX Primitive | Reached EOF before encountering closing brace or delimiter for macro argument. | Catalog Hint | 47_file_ended_while_scanning |
| 48 | Package amsmath Error: \split wont work here |
Package | split environment placed outside enclosing multiline math environment (equation, align, gather). |
Catalog Hint | 48_package_amsmath_split_wont_work |
| 49 | Package amsmath Error: \intertext only allowed in alignment env |
Package | \intertext or \shortintertext called outside an amsmath alignment environment (align, gather). |
Catalog Hint | 49_package_amsmath_invalid_intertext |
| 50 | LaTeX Error: Unknown float option 'foo' |
LaTeX Kernel | Invalid positioning specifier in float brackets; allowed are h, t, b, p, !, H. |
Catalog Hint | 50_unknown_float_option |
| 51 | Package tikz Error: ';' expected |
Package | TikZ drawing path or command terminated without mandatory closing semicolon ;. |
Catalog Hint | 51_package_tikz_missing_semicolon |
| 52 | Package pgfkeys Error: I do not know the key 'foo' |
Package | Unknown configuration key passed to TikZ/PGF macro; check spelling or load required TikZ library. | Catalog Hint | 52_package_pgfkeys_unknown_key |
| 53 | LaTeX Error: Not allowed in LR mode |
LaTeX Kernel | Vertical or display elements (lists, displays, paragraphs) placed inside an LR box (\mbox, \fbox). |
Catalog Hint | 53_not_allowed_in_lr_mode |
| 54 | Package enumitem Error: Key 'foo' is not defined |
Package | Unknown styling key passed to enumitem list options or \setlist. |
Catalog Hint | 54_package_enumitem_key_undefined |
| 55 | Package kvsetkeys Error: Undefined key 'foo' |
Package | Unknown key passed to key-value options parser used by packages like geometry or hyperref. |
Catalog Hint | 55_package_kvsetkeys_undefined_key |
4. On-Demand Error Corpus Testing
The reproducer cases in this directory provide verification fixtures. Each subdirectory contains:
example.tex: Minimal self-contained document triggering the error.README.md: Explanation of why the error occurs, the raw log signature, and how to resolve it.
Running Corpus Verification
To keep continuous integration and quality gates fast, the error corpus is executed on demand and completely decoupled from tools/gate:
# Run standalone verification across all 55 error corpus reproducers
rtk ./tools/test_error_corpus