Linter Rules
badness lint runs a set of built-in rules over each file’s parse tree and
reports a diagnostic for every finding. This page is the catalogue: one section
per rule, keyed by its stable rule id. That id is what appears in a
diagnostic, what [lint] select/ignore (and --select/--ignore) target,
and what a % badness-lint skip <id> comment suppresses.
Every rule is on by default; narrowing happens only through select/ignore
in the [lint] table (see the
Configuration reference). Where a rewrite is unambiguous a rule
carries an auto-fix: a safe fix (shown below as “After applying the fix”)
is applied by badness lint --fix; an unsafe fix, one that may change output
such as inserting a line-breaking tie, is applied only with --unsafe-fixes or
as an editor code action, so it has no “after” block here.
Each example below is linted live to produce its diagnostic and fixed output, so this page never drifts from the rules’ actual behavior.
This page covers the LaTeX linter. BibTeX files have a parallel set of rules
(a separate BibRule registry under src/bib/linter/), selectable through the
same [lint] config and catalogued in
BibTeX Linter Rules.
abbreviation-spacing
Flag TeX’s sentence-vs-interword spacing going wrong around abbreviations and acronyms (ChkTeX 12/13). Outside \frenchspacing, TeX widens the space after ./?/! unless the punctuation follows an uppercase letter. Two shapes defeat that: a lowercase abbreviation (e.g., i.e., etc., et al.) gets a too-wide space, fixed with \ (e.g.\ foo); and an uppercase acronym ending a sentence (USA.) gets a too-narrow space, fixed with \@ (USA\@.). To stay conservative the first fires only before a lowercase word (the sentence clearly continues) and the second only for a run of two or more capitals before the period and before an uppercase word (a new sentence), so initials (J.), dotted forms (U.S.A.), and mid-sentence acronyms are left alone. Both fixes are unsafe – they change the typeset spacing – so --fix leaves them alone while --unsafe-fixes and the editor code action apply them. The rule is silent under \frenchspacing, and never touches comments, verbatim, or math.
A lowercase abbreviation followed by more text takes an interword space:
We tried several methods, e.g. gradient descent.
warning: abbreviation-spacing
--> example.tex:1:31
|
1 | We tried several methods, e.g. gradient descent.
| ^ `e.g.` is an abbreviation, not a sentence end; use an interword space `\ ` (`e.g.\ `) so TeX does not widen the gap
An acronym ending a sentence takes intersentence spacing:
The rover reached the USA. Then it stopped.
warning: abbreviation-spacing
--> example.tex:1:26
|
1 | The rover reached the USA. Then it stopped.
| ^ capital before sentence-ending punctuation suppresses intersentence spacing; use `\@` (`Word\@.`) to restore it
blank-line-in-keyval
Flag a blank line at the top level of a key=value argument. A blank line is a \par token and a keyval processor walks its entries with macros that are not \long, so the call aborts – and the error TeX reports names the processor rather than the command the author wrote (\hypersetup yields “Paragraph ended before \kv@processor@default was complete”), which is what makes the finding worth more than the compiler’s own message. Scoped by measurement: a blank line nested inside a value’s brace group (\tikzset{aa/.style={draw,\n\nthick}}) compiles clean and is not flagged, an unclosed { is left to the parse error it already draws, and only the hand-curated signature tier is consulted. The autofix drops the blank line and keeps the following indentation; it is safe by construction, since it edits only whitespace and ContentKind::Keyval is exactly the claim that the processor strips spaces around entries.
A blank line separating two keys, which aborts the call:
\hypersetup{colorlinks=true,
linkcolor=blue}
error: blank-line-in-keyval
--> example.tex:1:29
|
1 | \hypersetup{colorlinks=true,
| _____________________________^
2 | |
3 | | linkcolor=blue}
| |_^ blank line in `\hypersetup`'s key-value argument; the `\par` aborts the call
After applying the fix:
\hypersetup{colorlinks=true,
linkcolor=blue}
duplicate-label
Flag a \label{key} defined more than once in the same label namespace – within one file, or across files that share a document when a project view is available. LaTeX itself only warns and silently keeps the last definition. Definitions in mutually exclusive branches of a TeX conditional (\iftrue...\else...\fi, \newif-defined conditionals included) are not duplicates and are not flagged. No autofix: resolving a collision (rename vs delete) is the author’s call.
The same key defined twice in one file:
\section{One}\label{sec:x}
\section{Two}\label{sec:x}
warning: duplicate-label
--> example.tex:2:14
|
1 | \section{One}\label{sec:x}
| ----- first definition of `sec:x`
2 | \section{Two}\label{sec:x}
| ^^^^^^^^^^^^^ label `sec:x` is defined more than once
deprecated-command
Flag the obsolete two-letter font switches (\bf, \it, \rm, \sf, \tt, \sc, \sl) that LaTeX 2e superseded with the \...series/\...shape/\...family declarations. \em is not flagged; it is still the supported emphasis switch. A name the file redefines (\renewcommand{\sl}{…}, \def\rm{…}) is the user’s macro, not the switch, so it is not flagged anywhere. The autofix swaps just the control word (\bf -> \bfseries), leaving any following text untouched, so it is correct by construction; it is withheld where the switch is merely referenced (\let\x\rm, \ifx\rm\y).
An obsolete two-letter font switch:
{\bf important}
warning: deprecated-command
--> example.tex:1:2
|
1 | {\bf important}
| ^^^ `\bf` is deprecated; use `\bfseries`
After applying the fix:
{\bfseries important}
missing-nonbreaking-space
Flag a plain space where a TeX tie (~) belongs, before a command whose output a line break would orphan: a bare-number reference (Figure \ref{x}, \eqref, \pageref) or a bracketed citation (see \cite{a}, \parencite, \autocite). A tie keeps the reference on the same line. Self-describing references (\autoref, \cref) and textual citations (\textcite, \citet) are not flagged – they emit their own noun, so a break orphans nothing. Both a same-line space and a single source line break before the command are flagged (a blank line is not – that starts a new paragraph). For a same-line space the fix is unsafe – inserting a tie changes line breaking – so --fix leaves it alone; --unsafe-fixes and the editor code action apply it. A line break is report-only: rewriting the newline to ~ would join the two lines, a reflow the formatter owns.
A plain space where a tie belongs before a cross-reference:
see Figure \ref{fig:plot}
warning: missing-nonbreaking-space
--> example.tex:1:11
|
1 | see Figure \ref{fig:plot}
| ^ missing non-breaking space before `\ref`; use a tie `~` so the reference stays on the same line
obsolete-environment
Flag math environments the community has superseded, naming the modern replacement in the message. The canonical case is eqnarray, which amsmath replaced with align decades ago (it mis-spaces relations and is a perennial l2tabu warning). The autofix renames the \begin/\end pair in place, leaving the body untouched, so it is correct by construction.
The superseded eqnarray environment:
\begin{eqnarray}
a &=& b
\end{eqnarray}
warning: obsolete-environment
--> example.tex:1:7
|
1 | \begin{eqnarray}
| ^^^^^^^^^^ `eqnarray` is obsolete; use `align`
After applying the fix:
\begin{align}
a &=& b
\end{align}
primitive-command
Flag raw plain-TeX primitives discouraged in LaTeX source, naming the LaTeX construct that supersedes each one (ChkTeX 41, lacheck, l2tabu). A sibling of deprecated-command, which covers the obsolete font switches. Most primitives are reported only: their LaTeX replacement restructures arguments (a \over b becomes \frac{a}{b}, \centerline{x} becomes a \centering declaration or a center environment), so no single textual edit can rewrite them correctly by construction. A few carry a Safe autofix — a 1:1 control-word swap for a primitive whose LaTeX form is a single meaning-identical token (\sb/\sp become _/^); the swap replaces just the control word, so it stays lossless and meaning-preserving, and is withheld where the primitive is merely referenced (\let\x\sp, \ifx\sp\y). A name the file redefines (\renewcommand\sp{…}) is the user’s macro, not the primitive, so it is not flagged anywhere.
A plain-TeX fraction primitive (report-only; the LaTeX form restructures its operands):
$a \over b$
warning: primitive-command
--> example.tex:1:4
|
1 | $a \over b$
| ^^^^^ `\over` is a raw TeX primitive; use `\frac{...}{...}`
The plain-TeX subscript alias, carrying a safe swap to _:
$x\sb2$
warning: primitive-command
--> example.tex:1:3
|
1 | $x\sb2$
| ^^^ `\sb` is a raw TeX primitive; use `_`
After applying the fix:
$x_2$
dollar-display-math
Flag plain-TeX $$...$$ display math. $$ is a TeX primitive that bypasses amsmath spacing hooks and breaks fleqn/\everydisplay, so LaTeX steers users to \[...\]. The autofix swaps the delimiters in place and leaves the body untouched, so it parses and stays lossless; it is withheld when the display math is unclosed.
Plain-TeX display math:
$$a + b = c$$
warning: dollar-display-math
--> example.tex:1:1
|
1 | $$a + b = c$$
| ^^ `$$…$$` is plain-TeX display math; use `\[…\]`
After applying the fix:
\[a + b = c\]
ellipsis
Flag a literal run of three or more periods (...) where a real ellipsis command belongs. ... sets three tight full stops; LaTeX’s ellipsis commands set correctly spaced dots. In text the fix is a safe swap to \dots (a space is added before a following letter so the control word cannot glue onto the next word). In math \ldots (baseline, for comma lists) and \cdots (centered, for operator chains) are not interchangeable, so the fix is unsafe: it guesses from the neighboring atoms – an operator or relation picks \cdots, otherwise \ldots – and applies only under --unsafe-fixes or as an editor code action. Comments and verbatim are never touched.
Literal dots in text:
See Chapter 2, 3, ... for details.
warning: ellipsis
--> example.tex:1:19
|
1 | See Chapter 2, 3, ... for details.
| ^^^ literal `...` ellipsis; use `\dots`
After applying the fix:
See Chapter 2, 3, \dots for details.
Literal dots in a math sum (an operator neighbor picks \cdots):
$a_1 + ... + a_n$
warning: ellipsis
--> example.tex:1:8
|
1 | $a_1 + ... + a_n$
| ^^^ literal `...` ellipsis; use `\cdots` in math (`\ldots` for lists, `\cdots` for operator chains)
hard-coded-reference
Flag a literal cross-reference written in prose – Figure 3, Table~1, Section 2 – instead of \ref/\cref to a \label (textidote sh:hcfig/hctab/hcsec). Hard-coding the number defeats LaTeX’s automatic numbering: renumbering a float or reordering sections silently breaks the reference and drops the hyperlink. The rule is report-only – the correct rewrite needs the label the number refers to, which is not in the text, so no autofix is offered. To stay conservative it fires only for a capitalized reference word (Figure, Table, Section, Eq., …) matched as a whole word and directly followed, across one space or a tie ~, by an arabic number; plurals, lowercase, Figure~\ref{x}, and Figure three are left alone. It also skips a citation locator (\cite[Section~8.1]{...}, a reference into external work), an environment title (\begin{thm}[Conway's Theorem 0], a proper name), and an \item[label] description-list caption (\item[Part 3.]). It never touches math, comments, or verbatim.
A hard-coded figure number instead of a cross-reference:
See Figure 3 for the results.
warning: hard-coded-reference
--> example.tex:1:5
|
1 | See Figure 3 for the results.
| ^^^^^^^^ hard-coded reference `Figure 3`; use `\ref`/`\cref` to a `\label` so the number stays in sync
Even tied with ~, the number is still hard-coded:
Table~1 lists the parameters.
warning: hard-coded-reference
--> example.tex:1:1
|
1 | Table~1 lists the parameters.
| ^^^^^^^ hard-coded reference `Table~1`; use `\ref`/`\cref` to a `\label` so the number stays in sync
straight-quotes
Flag a literal ASCII double quote (") used for quotation. In LaTeX a straight " always sets a closing double quote, so an opening one comes out backwards; the correct forms are `` (two backticks) to open and '' (two apostrophes) to close. A quotation is reported once, spanning both quotes, and its fix rewrites the pair in one atomic edit – so a single editor code action repairs it from either end. A quote left unpaired (no closer before the paragraph ends) reports on its own. The fix is unsafe: it infers direction from context – a quote preceded by whitespace, a line break, an opening delimiter ((, [, {), a backtick, or the start of the document opens, anything else closes – and applies only under --unsafe-fixes or as an editor code action, since the guess can flip the typeset glyph. Single straight quotes (') are left alone (they are legitimately apostrophes), and comments, verbatim, math, TeX hex constants ("2D), and \pdfmapline font maps are never touched.
Straight ASCII double quotes around a phrase:
He said "hello world" to me.
warning: straight-quotes
--> example.tex:1:9
|
1 | He said "hello world" to me.
| ^^^^^^^^^^^^^ straight double quotes; use `` `` `` (opening) and `''` (closing)
An opening quote after a parenthesis:
("quoted")
warning: straight-quotes
--> example.tex:1:2
|
1 | ("quoted")
| ^^^^^^^^ straight double quotes; use `` `` `` (opening) and `''` (closing)
swallowed-space
Flag a text-producing control word directly followed by a space that TeX eats, gluing the macro’s output to the next word (\LaTeX is renders “LaTeXis”) (ChkTeX 1). When TeX tokenizes a control word it discards following spaces, so the space never reaches the output. To stay conservative the rule fires only for a curated set of argument-less TeX-family logos (\LaTeX, \TeX, \BibTeX, …), only in text mode, and only when the next token is a word beginning with an alphanumeric character – a following period (\LaTeX . -> “LaTeX.”) is what the author wanted. The fix inserts {} after the control word (\LaTeX{} is), ending the macro name so the space survives; it is unsafe because it changes the typeset output, so --fix leaves it alone while --unsafe-fixes and the editor code action apply it.
A logo swallows the following space, gluing it to the next word:
We used \LaTeX to typeset this.
warning: swallowed-space
--> example.tex:1:15
|
1 | We used \LaTeX to typeset this.
| ^ `\LaTeX` swallows the following space; add `{}` (`\LaTeX{}`) or `\ ` so it prints
space-before-command
Flag a plain space directly before a command that should hug the preceding word – \footnote, \footnotemark, \index, \label (ChkTeX 24/42). A space before \footnote sets a spurious space before the footnote mark (word \footnote{x} -> “word ¹”); a space before a zero-width \index/\label leaves a stray inter-word gap that can shift the recorded page. The fix deletes the space. It is unsafe – removing the space changes the typeset spacing – so --fix leaves it alone while --unsafe-fixes and the editor code action apply it. To stay conservative only the same-line WORD SPACE \cmd shape is flagged (a space at line start or after a brace is left alone), and math is skipped (an inter-token space is insignificant there), covering both $…$ and math environments like equation/align. For the zero-width \index/\label the fix is withheld unless the group is trailed by whitespace, a newline, or paragraph end, since otherwise the leading space is a real interword space to the following content.
A space before a footnote sets a spurious space before the mark:
This is important \footnote{See the appendix.}
warning: space-before-command
--> example.tex:1:18
|
1 | This is important \footnote{See the appendix.}
| ^ spurious space before `\footnote`; delete it so no stray space is typeset before the command
mismatched-delimiter
Flag a \left ... \right pair whose delimiter glyphs point the wrong way – a closing glyph opening the pair, or an opening glyph closing it (\left) ... \right(). Deliberately conservative: only an orientation error is flagged, never a mere opener/closer mismatch, since half-open intervals like \left( ... \right] are legitimate. Structural faults (a missing \right) are reported by the parser, not this rule. No autofix: the intended glyphs are ambiguous.
A \left/\right pair whose glyphs point the wrong way:
$\left) x \right($
warning: mismatched-delimiter
--> example.tex:1:7
|
1 | $\left) x \right($
| ^ `\left)` uses a closing delimiter where an opening one is expected
warning: mismatched-delimiter
--> example.tex:1:17
|
1 | $\left) x \right($
| ^ `\right(` uses an opening delimiter where a closing one is expected
dash-length
Flag a dash of the wrong length for its context (ChkTeX 8). LaTeX sets a hyphen from -, an en dash from --, and an em dash from ---. Between two numbers a range takes an en dash, so 5-10 or 5---10 is flagged with an unsafe fix to -- (unsafe because it changes the typeset glyph and a hyphen between numbers is occasionally intentional). Between two words an en dash (--) is almost always a mistake, but whether a hyphen or an em dash was meant is ambiguous, so it is reported without a fix – except when it joins coordinate proper names (Barzilai--Borwein, Newton--Raphson), detected by an uppercase first letter on either flank, where the en dash is correct and the finding is suppressed. To stay conservative the rule only inspects a dash run that sits inside a single word with content on both sides and is the only dash run in that word, so dates (2020-01-15), ISBNs, spaced dashes, and option flags (--verbose) are left alone. Column spans in rule commands (\cline{1-3}, \cmidrule(lr){2-3}) and key arguments (\label{fig:1-3}, \cite{smith2020-1}) are specs and opaque identifiers rather than typeset ranges, so they are skipped too. Comments, verbatim, and math are never touched.
A hyphen where a number range wants an en dash:
See pages 5-10 for the proof.
warning: dash-length
--> example.tex:1:12
|
1 | See pages 5-10 for the proof.
| ^ hyphen between numbers; use an en dash `--` for a number range
An en dash between words (ambiguous, so reported without a fix):
A well--known result.
warning: dash-length
--> example.tex:1:7
|
1 | A well--known result.
| ^^ en dash `--` between words; use a hyphen `-` for a compound or an em dash `---` for a break
times-variable
Flag a literal x used as a multiplication sign between two numbers, such as 640x200 or 3x3 (ChkTeX 29). TeX sets that x as an italic letter rather than the \times cross, so it reads wrong. The rule only fires when the whole word is digits x digits – one lowercase x with ASCII digits on both sides and nothing else – so ordinary words (matrix), spaced products (n x m), hex literals (0xFF, 0x12), and key arguments such as \label{fig:3x3} or \ref{fig:3x3} (where the x is part of an opaque identifier) are left alone. The fix is unsafe (a bare x between numbers is usually a cross but occasionally a real variable): inside math it rewrites the x to \times, and in text it wraps it as $\times$ so the result still compiles. So --fix leaves it alone; --unsafe-fixes and the editor code action apply it.
A literal x as a multiplication sign in text (fixed to $\times$):
A 640x200 pixel image.
warning: times-variable
--> example.tex:1:6
|
1 | A 640x200 pixel image.
| ^ literal `x` as a multiplication sign between numbers; use `\times` for a cross
The same inside math mode (fixed to \times):
The grid is $640x200$ cells.
warning: times-variable
--> example.tex:1:17
|
1 | The grid is $640x200$ cells.
| ^ literal `x` as a multiplication sign between numbers; use `\times` for a cross
math-operator-name
Flag a bare log-like function name (sin, cos, log, lim, and the rest of the LaTeX/amsmath set) written in math mode without its backslash, so TeX sets it as italic variables instead of the upright \sin operator with correct spacing (ChkTeX 35). It fires when the name starts a WORD and ends at a word boundary, catching both $sin x$ and the glued $sin(x)$, while leaving words that merely begin with one (since) alone and preferring the longest match (sinh over sin). To stay conservative it only fires inside math mode, never in a subscript or superscript, where max in x_{max} is almost always a label rather than the operator (including inside a command argument such as \frac{x_{max}}{n}, whose body carries no script nodes), and never inside a key argument such as \label{eq:thing_max} or \eqref{eq:max}, whose content is an opaque identifier rather than typeset math. The fix inserts the backslash (sin -> \sin); it is unsafe because it changes the typeset output (upright glyph and operator spacing) and a bare sin is occasionally a real product, so --fix leaves it alone while --unsafe-fixes and the editor code action apply it.
A bare function name typesets as italic variables:
$sin x + cos x = 1$
warning: math-operator-name
--> example.tex:1:2
|
1 | $sin x + cos x = 1$
| ^^^ bare `sin` in math typesets as italic variables; use `\sin`
warning: math-operator-name
--> example.tex:1:10
|
1 | $sin x + cos x = 1$
| ^^^ bare `cos` in math typesets as italic variables; use `\cos`
It fires through the glued f(x) form too:
The limit $lim(x)$ diverges.
warning: math-operator-name
--> example.tex:1:12
|
1 | The limit $lim(x)$ diverges.
| ^^^ bare `lim` in math typesets as italic variables; use `\lim`
makeat-macro
Flag a macro whose name contains @ (\foo@bar, \p@, \@ifnextchar) used outside a \makeatletter/\makeatother region. There @ has its ordinary catcode, so it cannot be part of a control word: \foo@bar is read as \foo followed by the text @bar, not as a call to the internal macro \foo@bar. Usually the enclosing \makeatletter/\makeatother was forgotten. Because the formatter’s lexer already tracks \makeatletter state, this is decided exactly – an in-region name lexes as one token and is never flagged; only the split out-of-region form (control word abutting an @-word, or \@ abutting a letter-word) is. Report-only: a correct fix would mean wrapping the use in \makeatletter/\makeatother, not a tight local edit, so no autofix is offered. The end-of-sentence \@ (as in NASA\@.) is not flagged.
An internal @ macro used without \makeatletter:
\my@command
warning: makeat-macro
--> example.tex:1:1
|
1 | \my@command
| ^^^^^^^^^^^ `\my@command` uses `@` in a macro name outside a `\makeatletter` region; `@` is not a letter here, so this reads as `\my` followed by the text `@command`
A leading-@ macro (a \@-prefixed internal) outside a region:
\@ifstar{\StarredForm}{\PlainForm}
warning: makeat-macro
--> example.tex:1:1
|
1 | \@ifstar{\StarredForm}{\PlainForm}
| ^^^^^^^^ `\@ifstar` uses `@` in a macro name outside a `\makeatletter` region; `@` is not a letter here, so this reads as `\@` followed by the text `ifstar`
sectioning-level-jump
Flag a heading that descends more than one sectioning level below the preceding heading – \section straight to \subsubsection, skipping \subsection (textidote’s sh:secskip). Standard sectioning commands form a fixed ladder (\part, \chapter, \section, \subsection, \subsubsection, \paragraph, \subparagraph); descending it a rung at a time keeps the outline sound, and a jump usually signals the wrong command. Only downward jumps between consecutive headings are flagged – climbing back up to close sections is normal, as are repeated headings at one level. The comparison is relative to the previous heading, never an absolute top level, so an article opening with \section is fine. Report-only: repairing a skip (promote the heading or insert an intermediate one) is a structural choice for the author, not a correct-by-construction edit.
A heading that drops two levels at once (skipping \subsection):
\section{Introduction}
\subsubsection{Details}
warning: sectioning-level-jump
--> example.tex:2:1
|
2 | \subsubsection{Details}
| ^^^^^^^^^^^^^^ `\subsubsection` skips a sectioning level after `\section` (expected `\subsection`)
missing-required-argument
Flag a command invoked with fewer {…} groups than the required arity in its curated built-in signature (ChkTeX warning 14, decided on the parse tree and signature database rather than line heuristics). TeX also accepts unbraced single-token arguments (\frac12), so the rule stays silent whenever a following token could still supply the missing argument and fires only at a hard boundary: the end of the enclosing group, math shell, or environment, an alignment &, a \\ line break, a blank line, or the end of the file. Contexts where a bare command is deliberate are skipped – macro-definition bodies (\newcommand{\bold}{\textbf}), arguments of unknown commands, standalone {…} scope groups, \let-style alias forms, and names the file itself redefines. Report-only: the missing argument’s content is the author’s to write, so no fix is correct by construction.
A fraction missing its denominator:
$\frac{1}$
warning: missing-required-argument
--> example.tex:1:2
|
1 | $\frac{1}$
| ^^^^^ `\frac` is missing 1 of its 2 required arguments
A command left bare at the end of a group, with nothing to take:
\emph{see \textbf}
warning: missing-required-argument
--> example.tex:1:11
|
1 | \emph{see \textbf}
| ^^^^^^^ `\textbf` is missing its required argument
undefined-ref
Flag a \ref-family reference to a label defined nowhere in the document. Sound only when the label namespace is complete, so it stays silent unless the project view is closed (every include resolves to an analyzed file) and rooted. Inert on stdin or wherever no cross-file label resolution is available. No autofix.
A reference to a label defined nowhere in the document:
\ref{sec:intro}
warning: undefined-ref
--> example.tex:1:1
|
1 | \ref{sec:intro}
| ^^^^^^^^^^^^^^^ reference to undefined label `sec:intro`
undefined-citation
Flag a \cite-family key matching no entry in the document’s bibliography – the bibliographic analog of undefined-ref. Sound only over a closed, rooted namespace where every .bib resource resolves to an analyzed file, and suppressed entirely by a \nocite{*} wildcard (which marks every key as used). Inert without cross-file citation resolution. No autofix.
A citation of a key that matches no bibliography entry:
\cite{knuth:1984}
warning: undefined-citation
--> example.tex:1:1
|
1 | \cite{knuth:1984}
| ^^^^^^^^^^^^^^^^^ citation of undefined key `knuth:1984`
unreferenced-label
Flag a \label that no \ref-family command targets anywhere in the document. The mirror of undefined-ref, and sound only when the label namespace is complete, so it stays silent unless the project view is closed (every include resolves to an analyzed file) and rooted. Inert on stdin or wherever no cross-file label resolution is available. Report-only: removing the dead label or adding a reference are both valid, so there is no autofix.
A label that no \ref-family command ever targets:
\section{Intro}\label{sec:intro}
warning: unreferenced-label
--> example.tex:1:16
|
1 | \section{Intro}\label{sec:intro}
| ^^^^^^^^^^^^^^^^^ label `sec:intro` is never referenced
verbatim-trailing-text
Flag non-whitespace text after a verbatim-like environment’s \end{…} on the same line (ChkTeX warning 31). LaTeX closes a verbatim environment by scanning line by line to \end{verbatim} and then gobbling the rest of that line, so \end{verbatim} foo silently drops foo. Scoped to verbatim-like environments — read off the parse tree (an opaque VERBATIM_BODY, or a curated built-in verbatim name for the empty-body case) — because ordinary environments do not gobble their \end line. A trailing % comment is treated as trivia, not flagged. Report-only: whether to move or delete the swallowed text is the author’s call, so no fix is correct by construction.
Text after \end{verbatim} is silently discarded by LaTeX:
\begin{verbatim}
sample
\end{verbatim} and more
warning: verbatim-trailing-text
--> example.tex:3:16
|
3 | \end{verbatim} and more
| ^^^^^^^^ text after `\end{verbatim}` on the same line is silently discarded
duplicate-package
Flag a package loaded more than once in the same file with \usepackage/\RequirePackage (which share one package namespace). LaTeX loads a given package only once; a second load is redundant and, when the options disagree, an option-clash error. Loads in mutually exclusive branches of a TeX conditional (\iftrue...\else...\fi, \newif-defined conditionals included) are not duplicates and are not flagged; if-named macros that take brace arguments instead of a \fi terminator (\ifthenelse and friends) carry no recognized branches. No autofix: removing a load can drop options the survivor lacks, and which load to keep is the author’s call. Class loads (\documentclass/\LoadClass) are a separate concern and are not flagged.
The same package loaded twice:
\usepackage{amsmath}
\usepackage{amsmath}
warning: duplicate-package
--> example.tex:2:1
|
2 | \usepackage{amsmath}
| ^^^^^^^^^^^^^^^^^^^^ package `amsmath` is loaded more than once
missing-provides
Flag a package or class source (.sty/.cls) that never identifies itself with the matching \ProvidesPackage/\ProvidesClass. Every well-formed package declares its identity so LaTeX can log it and honor date-based compatibility checks; a .sty carrying only \ProvidesClass (wrong kind) still counts as missing. The rule is inert for any other extension – a .tex has nothing to provide, and a .dtx hides its declaration inside guarded macrocode. No autofix: writing a correct \Provides… line (placement, date, version) is the author’s call.
A package source with no self-identification (the docs are rendered against a .sty path):
\NeedsTeXFormat{LaTeX2e}
\RequirePackage{xcolor}
warning: missing-provides
--> example.sty:1:1
|
1 | \NeedsTeXFormat{LaTeX2e}
| ^^^^^^^^^^^^^^^ package file lacks `\ProvidesPackage`
unknown-option
Flag a \usepackage/\RequirePackage option that the loaded package never declares with \DeclareOption, which LaTeX reports as an “Unknown option” error at compile time. Checked only against packages that are analyzed project files (a sibling .sty) — no option data ships for system packages — and only when the package’s declared set is trustworthy: a \DeclareOption* default handler, a key-value option processor (kvoptions, \ProcessKeyOptions, …), option forwarding, or an \input in the package silences the rule, as does a key=value option. Class loads (\documentclass) are not checked: an unknown class option is not an error, it becomes an unused global option. No autofix: dropping or renaming the option is the author’s call.
With a sibling mypkg.sty:
\ProvidesPackage{mypkg}[2026/01/01 v1.0 Demo package]
\DeclareOption{draft}{}
\ProcessOptions\relax
Loading the sibling package with an option it never declares:
\usepackage[final]{mypkg}
warning: unknown-option
--> example.tex:1:13
|
1 | \usepackage[final]{mypkg}
| ^^^^^ unknown option `final` for package `mypkg`
redundant-script-braces
Flag braces around a single-token sub/superscript argument, which ^/_ bind without them (x^{2} is x^2). The autofix deletes the two braces and leaves the inner token untouched. It is withheld when dropping the braces would let the following character glue onto the argument and change meaning (x^{2}-3 stays braced — unspaced x^2-3 would re-lex 2-3 as one token; y_{\alpha}b stays braced — \alphab is one control word).
Redundant braces around a single-token script argument:
$x^{2}$ and $y_{\alpha}$
help: redundant-script-braces
--> example.tex:1:4
|
1 | $x^{2}$ and $y_{\alpha}$
| ^^^ redundant braces around a single-token script argument
help: redundant-script-braces
--> example.tex:1:16
|
1 | $x^{2}$ and $y_{\alpha}$
| ^^^^^^^^ redundant braces around a single-token script argument
After applying the fix:
$x^2$ and $y_\alpha$
unclosed-math-delimiter
Flag a math opener the parser silently demoted to a plain token because no closer was reachable – a $ with no matching $, a \[/\( with no \]/\), or a \left with no \right. Such a shape is routine data in macro code (>{$} array columns, \expandafter\@tempa\[\@nil), so the parser tolerates it without a diagnostic; in prose it is almost always a dropped closer. To stay clear of the macro-code cases the rule is conservative: it reports only an opener in document prose, staying silent when it sits inside a brace group or optional argument (\newcommand{...}{$}, the >{$} column spec), an expl3 region, or a macrocode body. No autofix: the correction (insert a closer, or delete a stray opener) is ambiguous.
An inline-math $ with no matching $:
Let $x = 1 be the base case.
warning: unclosed-math-delimiter
--> example.tex:1:5
|
1 | Let $x = 1 be the base case.
| ^ `$` has no matching `$` (unclosed inline math)
A display-math \[ with no matching \]:
The bound \[ x + y follows immediately.
warning: unclosed-math-delimiter
--> example.tex:1:11
|
1 | The bound \[ x + y follows immediately.
| ^^ `\[` has no matching `\]` (unclosed display math)
A \left with no matching \right:
$a + \left( b + c$
warning: unclosed-math-delimiter
--> example.tex:1:6
|
1 | $a + \left( b + c$
| ^^^^^ `\left` has no matching `\right`
label-before-caption
Flag a \label placed before the \caption inside a float (figure, table, and their starred forms). \label records \@currentlabel, which inside a float is set by \caption; a label above the caption therefore captures whatever the last \refstepcounter left behind — usually the enclosing section number — so \ref silently prints a number unrelated to the float. LaTeX gives no warning. Scoped to statement-level labels, so the recommended \caption{Text\label{x}} idiom and a \subcaptionbox{A\label{x}}{…} subfigure label are never touched; any earlier caption or hand-rolled \refstepcounter/\stepcounter also silences it, and a float with no caption is left alone. The fix moves the label to just after the first statement-level \caption, and is Unsafe because it changes what \ref prints (by design) from an inferred intent.
A \label above its \caption picks up the section counter, not the figure number:
\begin{figure}
\includegraphics{plot}
\label{fig:plot}
\caption{A plot.}
\end{figure}
warning: label-before-caption
--> example.tex:3:3
|
3 | \label{fig:plot}
| ^^^^^^^^^^^^^^^^ `\label` before `\caption` in this `figure` captures the enclosing counter, not the float number
Suppression
To suppress a rule at a single site, use a comment directive:
% badness-lint skip deprecated-command: legacy code, leave as-is
{\bf here}
The verb carries the scope. skip covers the next construct, off and on
delimit a region, and skip-file covers the whole file wherever it sits:
% badness-lint off deprecated-command: legacy chapter
{\bf here}
{\it and here}
% badness-lint on deprecated-command
Naming the <id> is optional; leaving it out suppresses every rule over that
same span. The : <reason> tail is optional everywhere.
% badness skip / off / on / skip-file do the same and turn off the
formatter at the same time; see Formatting
for the layout-only % badness-format spellings.
Parse diagnostics (rule id parse) are never suppressed by select/ignore.