[Tex/LaTex] Opaque error messages given by common environments

big-listenvironmentserrors

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.

Best Answer

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.

Related Question