Opaque error messages given by common environments

Question

This is a public-interest question.

The title of the question Why does this error keep popping up even though I clearly fixed it? poignantly expresses a fundamental truth of LaTeX usage: sometimes the error message just does not mean what it says. It is possible to get more information from TeX, but this operates at the lowest level possible: basic command-line interaction. No amount of this can make clear what went wrong conceptually.

Particularly insidious in this regard are environments that function as enormous macros, because the error is not reported at the line where it occurs but at the \end{} tag, where all the processing is done (of course, this can happen with a macro that takes huge arguments, but you hardly ever see those). For example, no useful diagnostics can ever be extracted from amsmath's align environment, because it measures its entire contents before typesetting them a second time at the end.

I think it would be useful to gather a (necessarily anecdotal and incomplete) list of frequently-occurring error messages issued by such environments and their interpretations. Specifically, I'm looking for answers of the form:

• An environment.

• A misleading error message produced by that environment, particularly one with useless line information.

• Typical input producing that error along with a useful description of what's wrong.

• An explanation of how the error in the input leads to an antinomy in TeX's processing that produces the message given.

I'll lead off with an explanation of the error in the first question I linked, as an example.

Answer 1

Environment: align (from the package amsmath) and eqnarray (core LaTeX, but don't use it).

Error message:

ERROR: Missing } inserted.

--- TeX said ---
<inserted text> 
                }
l.6 \end{align*}

Code used:

\documentclass{article}
\usepackage{amsmath}
\begin{document}
\begin{align*}
  a$
\end{align*}
\end{document}

What's wrong: The math shift $ doesn't belong in the middle of a display math environment. Actually, it would be wrong in the middle of any math environment, but the code $ a$ $ gives the much clearer error message Missing $ inserted, because the inner $ ends math mode and the last one, which was intended to end it, actually begins another one that is not completed.

The display math error, similar to the above:

\documentclass{articl
\begin{document}
\[
a$
\]
\end{document}

gives the diagnostic

ERROR: Display math should end with $$.

--- TeX said ---
<to be read again> 

l.4 a$

which is perfectly helpful and is what one would expect from align.

What's really wrong: align does a lot of complicated things, but ultimately creates a TeX alignment using \halign using a preamble given in amsmath.sty as \align@preamble and that, at its most basic level, functions like the following:

\halign{
  % Preamble
  &\hfil$\displaystyle{#}$%
  &$\displaystyle{#}$\hfil\cr
  % Whatever is in the align
  ....
}

The important feature of this is that #, the material in each cell of the alignment, is placed in braces: {#}; the point of this is to force the correct spacing for symbols at the ends, so that relations behave as though there are operands on both sides, and so on. If # = a$, then what is actually typeset in that cell is

$\displaystyle{a$}$

and the first thing TeX thinks is wrong is that we have left math mode before closing a brace group. It does not give the message Missing $ inserted because the actual error occurs at the extra $, when it sees that the group was not closed. In fact, there is nothing in the above expression containing material illegal outside of math mode after the extra $.

Finally, the reason the message only references the \end{align} is that align, like the environ package, slurps the entire contents of the environment before using any of it, which only occurs (eventually) in the \end{align} tag, so TeX associates the error with this line of the input file, where it is executed, rather than where it is written.

Answer 2

Environment: array, eqnarray and others.

Error message:

! Missing number, treated as zero.
<to be read again>
                   f
l.100 \end{rray}

Input that caused the error:

\begin{array}
 a+b\\
 [f,g]\\
 m+n
\end{array}

What's really wrong: In a multiline construction, a bracketed dimension specifies additional vertical space following a line, so something like [2pt] was expected. If that's not what was wanted, enclose the bracketed expression in braces {[f,g]} (or even just the opening bracket, {[}, although this makes the input harder to read).

amsmath has provided a workaround: if there is a space between the \\ and the bracketed expression, it will not be interpreted as a spacing command. (however, if extra space is wanted, be sure to input the directive like this: \\[2pt], with no space. this works only for environments defined by amsmath and not in the basic latex complement.)

Answer 3

Environment: alignat (from the package amsmath).

Error message:

! Missing number, treated as zero.
<to be read again>
                   a
l.100 \end{alignat}

Input that caused the error:

\begin{alignat}
 a&  =b&  c& =d\\
a'& =b'& c'& =d'
\end{alignat}

What's really wrong: The alignat environment requires a numeric argument to tell it how many "equation columns" are to be allowed in each row.

To fix, count the maximum number of & in any row, divide by 2, and add 1. Then change the first line (for this example) to

\begin{alignat}{2}

Answer 4

This is very particular, but still valid in my opinion.

Macro: Macros with optional arguments (like \section, \caption, ...) that use grouping together with square brackets.

Error message:

! Extra }, or forgotten $.
\\mymacroA [#1]#2->{#1}
                       \ #2
l.10 \mymacroA[$a[b]$
                     ]{$c$}

Input that caused the error:

\newcommand{\mymacroA}[2][x]{{#1}\ #2}% or {#1\ {#2}}
\mymacroA[$a[b]$]{$c$}

What's really wrong: At first, it's not clear why there is an error, since the input seems perfectly legit. However, the setup for the optional argument expects a balanced group spanned by [ on the left and ] on the right. In the construction

\mymacroA[$a[b]$]{$c$}

the first balanced [..] groups $a[b, which is passed as the first argument #. Subsequently, the mandatory argument #2 is the following token (since no braced group {...} is present) $. The replacement text for \mymacroA therefore results in

{$a[b}\ $

(followed by ]{$c$} which has nothing to do with \mymacroA). While the original setup seems to have balanced components everywhere (outer [..] with inner $..$), the replacement text reveals the obvious problematic interpretation by the TeX engine. The grouping inside \mymacroA together with the splitting of the balanced input produces a "extra }" or "forgotten $ error.

A basic fix is to shield/conceal the square brackets in {..} at the argument level

\mymacroA[$a{[b]}$]{$c$}

and possibly compensate for lost math spacing manually, if needed. A more complex fix is provided by xparse:

\usepackage{xparse}% http://ctan.org/pkg/xparse
\NewDocumentCommand{\mymacroB}{O{x} m}{{#1}\ #2}% or {#1\ {#2}}

It has a "less greedy" approach to assembling the optional arguments' contents in this instance.

It is very common to use the above format and it typically occurs when passing ToC-related contents to a sectioning command that has math content:

\section[The function $f[x]$]{The function $f[x]$ is awesome}

or

\caption[The function $f[x]$]{The function $f[x]$ is awesome}

References:

• LaTeX error bad math environment delimiter inside subfloat caption
• Error using \( … \) environment inside \section argument
• \( \) don't work with ToC?

---

When using the LaTeX syntax \(..\) together with fixltx2e, the error message

! LaTeX Error: Bad math environment delimiter.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...                                              

l.4 \section[\(a[b]\)
                      ]{C}

is produced from the MWE:

\documentclass{article}
\usepackage{fixltx2e}% htpp://ctan.org/pkg/fixltx2e
\begin{document}
\section[\(a[b]\)]{C}
\end{document}

Here again, the balanced environment \(..\) and optional/mandatory grouping seems perfectly fine. However, a same discussion as above is relevant with math mode being lost somewhere along the line.