7 Understanding Error Messages

TeX and LaTeX error messages can be cryptic, but sometimes it's possible to at least find out where things have gone wrong by studying the message.

Consider the following document:

\documentclass{article}

\newcommand{\example}[1]{#1}

\begin{document}
This is a sample document that contains a long 
command \example{with an error.

This is the next paragraph
\end{document}

This produces the following error message:

Runaway argument?
{with an error. \par This is the next paragraph \end {document}
! File ended while scanning use of \example.
<inserted text>
                \par

The first line (“Runaway argument?”) indicates the type of error. A runaway argument is usually caused by a missing closing brace. The next line indicates where TeX got up to before things started to go wrong. In this error message there is no line number but you can use the information that has been supplied to help you track where the error might be. Copy the first part of this line (say {with an error) and paste it into your editor's search function. This should take you to the relevant line where you can see that there is no closing brace.

Suppose, instead, the document looked like:

\documentclass{article}

\newcommand*{\example}[1]{#1}

\begin{document}
This is a sample document that contains a short 
command \example{with an error.

This is the next paragraph
\end{document}

In this case the error message is:

Runaway argument?
{with an error.
! Paragraph ended before \example was complete.
<to be read again>
                   \par
l.8

In this example, the error message includes the line number where things started to go wrong (l.8) so I can use my text editor's “go to line” function.

Sometimes the line number given in the error message doesn't correspond to the line number where the error actually occurs. For example, consider the following document:

\documentclass{report}

\author{A.N. Author}
\title{A sample document with a \badcommand}
\date{14th November, 2008}

\begin{document}
\maketitle
\end{document}

In this document the error is an undefined command (\badcommand) occurring on line 4. However, the error message is:

! Undefined control sequence.
\@title ->A sample document with a \badcommand

l.8 \maketitle

which indicates that the problem occurs on line 8. This is because TeX doesn't actually try to interpret \badcommand until line 8 when \maketitle tries to typeset the title page.

When this type of situation occurs, it may be necessary to do a little bit of detective work to try to trace the problem. In the above example, there are two methods to try:

The first line of the error message states the nature of the error (an undefined control sequence) and the second line indicates that the undefined control sequence is \badcommand. You can then use your text editor to search for any instances of \badcommand and replace it with the correct command. Alternatively, if you have forgotten to use a package that defines the command or, in the case of a custom command, you have forgotten to define the command, then do so.
The last line of the error message states that the problem was encountered on line 8 which contains the command \maketitle. What commands affect \maketitle? For the standard classes, such as report, these are: \author, \title and \date, so inspect the code where these commands are used. Try commenting out all but one of the commands and see if the error still occurs. For example, if I comment out the lines containing the title and date, the error goes away, but if I comment out the author and date instead, the error remains. This means that the error is in the title.

If you have many files that have been input (using, for example, \input or \include) you may find it a little difficult to work out which file the line number is referencing. Does l.8 refer to line 8 of my main file mydoc.tex or does it refer to line 8 of one of the files that have been input? In this case, you may find it easier to use the -file-line-error option when you run LaTeX (or PDFLaTeX etc):

pdflatex -file-line-error mydoc.tex

Now the error will be preceded by the file name and line number in the form:

./mydoc.tex:8: Undefined control sequence.

For further information on understanding error messages, see How to approach errors on the UK TeX FAQ. There is also a list of some common error messages in the document LaTeX for Complete Novices which is available from the same site as this document.

⇦

⇧

⇨