\chapter{Errors}\label{errors} \index{errors} You should look at this chapter when you get an error or warning message that you can't cope with. The first time the instructions given in Section~\ref{running-ex} for dealing with errors prove inadequate, you should read the following section. The other sections of this chapter should be used for finding out about what specific error messages or warnings mean. \section{About Errors} In Section~\ref{running-ex}, you learned first aid for dealing with errors. That material will get you through the more common simple errors. Here, you'll find out what to do when things are more serious. First of all, let's return to the question of finding out where the error occurred. Remember that \TEX's error messages include an error \index{error locator} locator that starts with a line number. Most of the time, the line number is something like ``{\tt l.4}'', meaning that the error was found when processing the fourth line from the beginning of the file. However, if your text editor allows you to break your file into \index{pages, in input file} pages, then the line number might be something like ``{\tt p.3,l.4}'', which indicates the fourth line of the third page of the file. If your input is all on a single file, then the error locator unambiguously identifies where \TEX{} thinks the problem is. However, if you're using the commands of Section~\ref{parts} to split your input into several files, then you need to know what file the error is in. \TEX{} uses the following device to tell you what file it's processing. Whenever it starts processing a file, it prints a \xsp{}{\tt (}\xsp{} followed by the file name, and when it finishes processing a file it types a \xsp{}{\tt )}\Xsp. For example, suppose \TEX{} types the following. \begin{small} \begin{verbatim} ...\ (MYFILE.TEX.13 [1] [2] [3] (PART.TEX.4 [4] [5]) [6] ! Undefined control sequence. l.249 \newpag ? \end{verbatim} \end{small} \noindent The first \xsp{}{\tt (}\xsp{} and file name tells us that \TEX{} began processing the file \hbox{\tt myfile.tex}. (Don't worry about the extra stuff attached to the file name; it will depend upon the operating system and isn't of much interest.) After producing the first three pages of output, it began processing {\tt part.tex}. After producing the next two pages of output, it finished processing {\tt part.tex} and resumed processing {\tt myfile.tex}. While it was producing output page~7, when it was processing line~279 of the file {\tt myfile.tex}, \TEX{} found an error. (In this case, it was a misspelled \verb"\newpage" command.) This tells you you where \TEX{} thinks the error is, but how do you figure out where it really is? In most cases, the error is right where \TEX{} tells you it is. However, if you can't see anything wrong with the input right there, then the problem may lie elsewhere. If the error was found by \LATEX{}, then you can look up the error-indication message in Section~\ref{latex-errors} on page~\pageref{latex-errors} to find out what went wrong. If the error was found by \TEX, then Section~\ref{tex-errors} on page~\pageref{tex-errors} might list the error message and help you figure out what caused it. If this doesn't help, then you'll have to wait until \LATEX{} has finished so you can return to the text editor and look at your input file. To find the cause of a mysterious error, you should scan backwards from the point where \TEX{} found the error. Here is a list of common mistakes to check for. \begin{itemize} \item Improperly matching braces. \item A missing math-mode delimiter---one of the commands \begin{verbatim} \[ \] \( \) $ \end{verbatim} \item A missing \verb"\end"\index{!end} command. \item A missing command argument. \item A \xsp{}{\tt [}\xsp{} in the text begin mistaken for an optional argument. \item Trying to do something in LR or math mode that can be done only in paragraph mode. \item Trying to do something in paragraph or LR mode that can be done only in math mode. \end{itemize} If looking at the input doesn't help, look at the output. If you were able to use the \verb"\stop"\index{!stop} command to stop \LATEX, then you will have output right up to the point where it stopped. By examining the last part of the output very carefully, you can often figure out exactly where things started going wrong, which may provide the necessary clue. When all else fails, you can isolate the error by dividing your input into small pieces and running them through \LATEX{} separately. In this way, you can very quickly isolate the error to a very small section of text, which should be enough to enable you to see what the problem is. If, after discovering the \LATEX{} command that caused the error, you still don't see anything wrong there, go back and read the section of this manual that describes that command. Then, if you still don't see what's wrong, consult a local expert. \section{\LATEX's Error Messages}\label{latex-errors} Here is a complete alphabetical list of \LATEX's error indicators, together with their causes. \yspace \noindent {\tt ! Bad \bs line or \bs vector argument.}\\ The first argument, which specifies the slope, of a \verb"\line"\index{!line} or \verb"\vector"\index{!vector} command is illegal. Look up the constraints on this argument in Section~\ref{pictures} on page~\pageref{pictures}. \yspace \noindent {\tt ! Bad math environment delimiter.}\\ You either have a \xsp{}\verb"\]"\index{!]}\xsp{} or \xsp{}\verb"\)"\index{!)}\xsp{} command without a corresponding \xsp{}\verb"\["\index{![}\Xsp or \xsp{}\verb"\("\index{!(}\Xsp, or else you've used a \xsp{}\verb"\["\xsp{} or \xsp{}\verb"\("\xsp{} in math mode. The problem is probably that your math mode delimiters don't match, but it could also be caused by unbalanced braces. \yspace \noindent {\tt ! Bad use of \bs\bs.}\\ You issued a \verb"\\" command between paragraphs in paragraph mode, where the command makes no sense. \yspace \noindent {\tt ! \verb"\begin{...}" ended by \verb"\end{...}".}\\ \LATEX{} has found an \verb"\end"\index{!end, unmatching} command that doesn't match the corresponding \hbox{\verb"\begin"}\index{!begin, unmatched} command. You probably misspelled the environment name in the \verb"\end" command, have an extra \hbox{\verb"\begin"}, or else forgot an \verb"\end", \yspace \noindent {\tt ! Command name ...\ already used}\\ You are trying to use a \verb"\newlist"\index{!newlist}, \verb"\newtheorem"\index{!newtheorem}, \verb"\newcommand"\index{!newcommand} or \hbox{\verb"\newlength"}\index{!newlength} command to define a command name that is already defined. You'll have to choose a new command name, or else, in the case of \verb"\newcommand", switch to a \verb"\renewcommand"\index{!renewcommand}. \yspace \noindent {\tt ! Counter too large.}\\ \LATEX{} is trying to number something greater than 26 with a letter. You're either making a very long list, or else you've been messing around with counter values. \yspace \noindent {\tt ! Environment ...\ undefined.}\\ You have issued a \verb"\begin"\index{!begin} command for a nonexistent environment. You probably misspelled the environment name. \yspace \noindent {\tt ! Float(s) lost.}\\ You put a {\tt figure}\index{figure environment} or {\tt table}\index{table environment} environment or a \verb"\marginpar"\index{!marginpar} command inside a box---for example, by placing it a footnote. Remember that such migrating text can be used only in outer paragraph \index{outer paragraph mode} mode. \LATEX{} probably discovered this long after it passed the offending environment or command, so you may have to check quite a ways back through your input to find where you made the error. \LATEX{} has lost one figure, table or marginal note. However, the one it lost is not necessarily the one that was put in the wrong place. \yspace \noindent {\tt !Illegal character in preamble.}\\ You have an illegal character in the argument of an {\tt array}\index{array environment} or {\tt tabular}\index{tabular environment} environment, or in the second argument of a \verb"\multicolumn"\index{!multicolumn} command. \yspace \noindent {\tt ! Missing \verb"\begin{document}".}\\ \LATEX{} tried to produce output before encountering a \verb"\begin{document}" command. If you didn't forget the \verb"\begin{document}", then there's something wrong in your input file before that command. The problem may be a stray character or an error in some declaration---for example, omitting the braces around an argument or forgetting the \xsp{}\verb"\"\xsp{} in a command name. \yspace \noindent {\tt ! Missing p-arg in preamble.}\\ You have a \xsp{}{\tt p}\xsp{} not followed by an expression in braces in the argument of an {\tt array}\index{array environment} or {\tt tabular}\index{tabular environment} environment, or in the second argument of a \hbox{\verb"\multicolumn"}\index{!multicolumn} command. \yspace \noindent {\tt ! Missing @-exp in preamble.}\\ You have an {\tt @} character not followed by an {\tt @}-expression in the argument of an {\tt array}\index{array environment} or {\tt tabular}\index{tabular environment} environment, or in the second argument of a \hbox{\verb"\multicolumn"}\index{!multicolumn} command. \yspace \noindent {\tt ! \bs newnumbering of ...\ illegal}\\ You're using a \verb"\newnumbering"\index{!newnumbering} command to try to change the numbering of something that you can't. You're probably trying \begin{verbatim} \newnumbering{enumerate}{...} \end{verbatim} which isn't allowed. Reread Section~\ref{counters} on page~\pageref{counters}. \yspace \noindent {\tt ! No such counter.}\\ You have specified a nonexistent counter in a \verb"\setcounter"\index{!setcounter}, \hbox{\verb"\addtocounter"}\index{!addtocounter} or \hbox{\verb"\newnumbering"}\index{!newnumbering} command. This was probably a typing error. \yspace \noindent {\tt ! Not in outer par mode.}\\ You had a {\tt figure}\index{figure environment} or {\tt table}\index{table environment} environment or a \verb"\marginpar"\index{!marginpar} command in math mode or inside a box. Remember that a command to produce migrating text can be used only in outer paragraph mode. \yspace \noindent {\tt ! \bs pushtabs and \bs poptabs don't match.}\\ \LATEX{} found a \hbox{\verb"\poptabs"}\index{!poptabs, unmatching} with no matching \hbox{\verb"\pushtabs"}\index{!pushtabs}, or has come to the \hbox{\verb"\end{tabbing}"} command with one or more unmatched \hbox{\verb"\pushtabs"} commands. \yspace \noindent {\tt ! Tab overflow.}\\ A \verb"\="\index{!=} command has exceeded the maximum number of tab stops that \LATEX{} permits. If you really need them, you might be able to convince a local expert to modify \LATEX{} so it allows more tab stops. \yspace \noindent {\tt ! There's no line here to end}\\ You are using a \verb"\newline"\index{!newline} or \verb"\\"\index{!!} command in paragraph mode between paragraphs, where the command makes no sense. \yspace \noindent {\tt ! This is a LaTeX bug.}\\ This shouldn't happen. If it does, then there's an error in \LATEX{} itself and you should call an expert for help. Save the input that generated the error, so we can find out exactly where \LATEX{} went wrong. \yspace \noindent {\tt ! Too deeply nested.}\\ You have more than six list \index{list environments, nested too deeply} environments or more than four {\tt enumerate} \index{enumerate environments, nested too deeply} environments nested within one another. Environments such as {\tt quote}\index{quote environment} and {\tt verse}\index{verse} count as list environments. \yspace \noindent {\tt ! Too many unprocessed floats.}\\ \LATEX{} has run out of room to store figures, tables and marginal notes. This probably means that you have put a huge number of {\tt figure} \index{figure environment} or {\tt table} \index{table environment} environments or \verb"\marginpar"\index{!marginpar} commands on a single page. It may also be caused by giving optional placement arguments to {\tt figure} or {\tt table} environments, or setting the float-placement parameters\index{float-placement parameters}, in such a way that the figures and tables can't be put anywhere. Try moving some of your {\tt figure} and {\tt table} environments further back in your input. \yspace \noindent {\tt ! Two-column float on one-column page.}\\ You have given a {\tt figure*} \index{figure* environment} or {\tt table*} \index{table* environment} environment when \LATEX{} is not producing two-column output. \yspace \noindent {\tt ! Typeface not available.}\\ You are trying to use a typeface \index{typeface, unavailable} that is not available in your system's version of \LATEX{}---probably some exotic type style in an unusual size. You might be able to persuade the local wizards to create a new version of \LATEX{} with that typeface, but you can probably live without it. \yspace \noindent {\tt ! Undefined tab position.}\\ You are using a \xsp{}\verb"\>"\Xsp, \xsp{}\verb"\+"\Xsp, \xsp{}\verb"\-"\Xsp, or \xsp{}\verb"\<"\xsp{} command to try to step to a nonexistent tab position. \yspace \noindent {\tt ! \verb"\<" in mid line.}\\ You are using a \xsp{}\verb"\<"\xsp{} command in the middle of a line in a tabular environment. The \xsp{}\verb"\<"\xsp{} command may appear only at the beginning of a line. \section{\TEX's Error Messages} \label{tex-errors} Here is an alphabetical list of some of \TEX's error messages and what may have caused them. \yspace \noindent {\tt ! Double subscript.}\\ There are two subscripts\index{subscripts, double} in a row in a mathematical formula---i.e., you typed something like \xsp{}\verb"xâ??{2}â??{3}"\Xsp, which makes no sense. If you meant \xsp{}$xâ??{2â??{3}}$\Xsp, then you should have typed \xsp{}\verb"xâ??{2â??{3}}"\Xsp. \yspace \noindent {\tt ! Double superscript.}\\ There are two superscripts\index{superscripts, double} in a row in a mathematical formula---i.e., you typed something like \xsp{}\verb"x^{2}^{3}"\Xsp, which makes no sense. If you meant \xsp{}$x^{2^{3}}$\Xsp, then you should have typed \xsp{}\verb"x^{2^{3}}"\Xsp. \yspace \noindent {\tt ! Extra alignment tab has been changed to \bs cr.}\\ You are trying to put too many column entries into a single row in an \hbox{\tt array}\index{array environment} or \hbox{\tt tabular}\index{tabular environment} environment. In other wordâ?¥l there were too many \verb"&"'s\index{!!ampersand} before the end of the row. \yspace \noindent {\tt ! Extra \verb"}", or forgotten \verb"$".}\\ Your braces or \verb"$"'s don't match properly. You've probably forgotten a \xsp{}\verb"{"\xsp{} or \xsp{}\verb"$"\xsp{} somewhere. \yspace \noindent {\tt ! I can't find file `...'.}\\ \TEX{} couldn't find the input file that you asked for. You can get this as a result of typing in the wrong file name when you start \LATEX, or specifying a nonexistent input file with an \verb"\input"\index{!input, missing file} or \verb"\include"\index{!include, missing file} command. When this error occurs, \TEX{} will type \begin{verbatim} Please type another input file name: \end{verbatim} and wait for you to type the correct file name. \yspace \noindent {\tt ! Illegal unit of measure (pt inserted).}\\ If you just got an \begin{verbatim} ! Illegal number, treated as zero. \end{verbatim} message, then this is part of the same problem. If not, it means that \LATEX{} was expecting a length as an argument and it got a number instead. The most common cause of this error is writing \xsp{}{\tt 0}\xsp{} for a length of zero instead of writing \xsp{}{\tt 0in}\Xsp. In this case, you can type \carrtn{} and your output should be all right. However, the error can also be caused by omitting a mandatory argument. \yspace \noindent {\tt ! Illegal parameter number in definition of ...\ .}\\ This is probably caused by a \hbox{\verb"\newcommand"}\index{!newcommand} or \hbox{\verb"\renewcommand"}\index{!renewcommand} command in which you used an argument number that's bigger than the number of arguments---for example, you might have put a \xsp{}\verb"#3"\xsp{} in the second mandatory argument after specifying that the command you're definiting should have only two arguments. If the ``{\tt ...}'' in the error indicator is \verb"\@gtempa"\index{!@gtempa}, then you've probably put a \xsp{}\verb"#"\xsp{} in the argument of a \verb"\label"\index{!label} command. \yspace \noindent {\tt ! Misplaced alignment tab character \verb"&".}\\ You've used the special character \xsp{}\verb"&"\index{!!ampersand}\xsp{} in ordinary text. You probably meant to type \xsp{}\index{!!!!ampersand}\verb"\&"\xsp{}. \yspace \noindent {\tt ! Missing control sequence inserted.}\\ You have probably typed a \verb"\newcommand"\index{!newcommand}, \verb"\renewcommand"\index{!renewcommand} or \verb"\newlength"\index{!newlength} command whose first argument is not a command name. \yspace \noindent {\tt ! Missing number, treated as zero.}\\ \TEX{} was probably in the middle of executing a \LATEX{} command that expected either a number or length as an argument and didn't get one. Perhaps you omitted a mandatory argument, or a square bracket in your text was mistaken for the beginning of an optional argument. \yspace \noindent {\tt ! Missing \verb"{" inserted.}\\ {\tt ! Missing \verb"}" inserted.}\\ \TEX{} has gotten confused somewhere along the line. These error messages often occur after the point where the incorrect input is. \yspace \noindent {\tt ! Missing \verb"$" inserted.}\\ \TEX{} probably a command that can be used only in math mode when it wasn't in math mode. The commands of Section~\ref{math} are designed for making mathematical formulas and must be used in one of the math environments. Remember that \TEX{} is not in math mode when it begins processing the argument of a box-making command, even if that command is in a math environment. This error also occurs if \TEX{} encounters a blank line when it's in math mode. \yspace \noindent {\tt ! Not a letter.}\\ You may have put something in the argument of a \verb"\hyphenation"\index{!hyphenation} command that doesn't belong there. \yspace \noindent {\tt ! Paragraph ended before ...\ was complete.}\\ You have a blank line in a command argument where it doesn't belong. You probably forgot the right brace at the end of an argument. \yspace \noindent {\tt ! TeX capacity exceeded, sorry [...].}\\ \TEX{} has just run out of space and aborted its execution. Before you panic, remember that the least likely cause of this error is that \TEX{} doesn't have the capacity to process your document. You probably made some error that caused \TEX{} to keep chasing its tail until it ran out of room. The end of the error indicator tells you what kind of space \TEX{} ran out of. The following are the cases in which you there's a reasonable chance that you actually exceeded \TEX's capacity. \begin{description}{{\tt exception dictionary}:} \item[{\tt box memory size}:] You may be creating so complicated a page of output that \TEX{} can't hold all the information needed to generate it. Such complicated output can be produced by large \index{tabbing environment}\hbox{\tt tabbing}, \index{tabular environment}\hbox{\tt tabular}, \index{array environment}\hbox{\tt array} and \index{picture environment}\hbox{\tt picture} environments. \TEX's space may also be filled up with figures and tables waiting for a place to go. To find out if you've really exceeded \TEX's capacity, put a \hbox{\verb"\clearpage"}\index{!clearpage} command in your file right before the place where \TEX{} ran out of room and try running it again. If it doesn't run out of room with the \verb"\clearpage" command there, then you did exceed its capacity. If it still runs out of room, then there's probably an error in your file. What can you do if you have run \TEX{} out of room? \TEX{} always processes a complete paragraph before deciding where to start a new page. Inserting a \verb"\newpage" command may save the day by letting \TEX{} write out the current page without having to process the part of the paragraph that goes on the next page. If the problem is caused by accumulating figures and tables, you can try to prevent them from accumulating---either by moving them further back in the document or by trying to get them to come out sooner. See Section~\ref{float-place} on page~\pageref{float-place} to find out how to do this. \item You have used \verb"\hyphenation"\index{!hyphenation} commands to give \TEX{} more hyphenation information than it has room for. \item[{\tt hash size}:] You ran \TEX{} out of room by defining too many command names and/or using too many cross-ref\-er\-encing labels. \item[{\tt pool size}:] You probably ran \TEX{} out of room by using too many cross-ref\-er\-encing \index{cross-referencing labels, using too many} labels and/or defining too many new command names. More precisely, the labels and command names that you defined have too many characters, so you can try using shorter ones. However, before assuming that this is the case, make sure you didn't forget a right brace on the argument of a counter \index{counter command} command like \hbox{\verb"\setcounter"}, or in a \hbox{\verb"\newtheorem"} or \hbox{\verb"\newlist"} command. \end{description} \yspace \noindent {\tt ! Text line contains an invalid character.}\\ Your input contains one of those weird characters that I warned you about in Section~\ref{input-file}. \yspace \noindent {\tt ! Undefined control sequence.}\\ You probably spelled a command name incorrectly. In this case, if you type \xsp{}{\tt H\carrtn}\xsp{}, \TEX{} will tell you how to type in the correct command, but you'll still have to change your input file later. \TEX{} may also produce this message in the middle of executing a \LATEX{} command. This probably means that there's a \LATEX{} command in the wrong place---for example, an \verb"\item" command that's not inside a list environment. Another possibility is that you left out the \hbox{\verb"\pagelayout"}\index{!pagelayout, forgetting} or \hbox{\verb"\documentstyle"}\index{!documentstyle, forgetting} command. \yspace \noindent {\tt ! Use of ...\ doesn't match its definition.}\\ If the ``{\tt ...}'' is a \LATEX{} command, then it's probably one of the commands for drawing pictures described in Section~\ref{pictures}, and you probably used the wrong syntax for specifying an argument. If it's \xsp{}\verb"\@array"\index{!@array}\xsp{} that doesn't match its definition, then you have put something you shouldn't have in an {\tt @}-expression in the argument of an {\tt array}\index{array environment} or {\tt tabular}\index{tabular environment} environment. Otherwise, I don't know what you might have done wrong; you'll have to figure it out yourself. \yspace \noindent {\tt ! You can't use `macro parameter character \verb"#"' in ...\ mode.}\\ You've used the special character \xsp{}\verb"#"\index{!!sharp}\xsp{} in ordinary text. You probably meant to type \xsp{}\index{!!!!sharp}\verb"\#"\xsp{}. \section{\LATEX{} Warnings} \LATEX's warning messages all begin with \begin{verbatim} LaTeX Warning: \end{verbatim} Below is an alphabetical list of all such warning messages and what they mean. \yspace \noindent {\tt Citation `...' on page ...\ undefined.}\\ The symbolic citation name in a \verb"\cite" command was not defined by a \verb"\bibitem" command. \yspace \noindent {\tt Label `...' multiply defined.}\\ Two \verb"\label"\index{!label} or \verb"\bibitem"\index{!bibitem} commands had the same argument the last time \LATEX{} processed your input. \yspace \noindent {\tt Label(s) may have changed. Rerun to get cross-references right.}\\ The numbers printed by \verb"\ref"\index{!ref}, \verb"\pageref"\index{!pageref} or \verb"\cite"\index{!cite} commands may be wrong. \yspace \noindent {\tt Marginpar on page ...\ moved.}\\ A marginal \index{marginal note, moved} note had to be moved down on the page to avoid printing on top of a previous marginal note. It will therefore not line up with the place in the text where the \verb"\marginpar"\index{!marginpar} command appeared. \yspace \noindent {\tt Oval too small.}\\ An \verb"\oval"\index{!oval,too small} command specified an oval so small that \LATEX{} can't draw small enough quarter-circles to put in its corners, so it had to draw a funny-looking oval. \yspace \noindent {\tt Reference `...' on page ...\ undefined.}\\ The argument of a \verb"\ref"\index{!ref, undefined} or \verb"\pageref"\index{!pageref, undefined} command was not defined by a \hbox{\verb"\label"}\index{!label} command. If you don't understand why it wasn't, see Section~\ref{aux} on page~\pageref{aux}. \section{\TEX{} Warnings} You can tell a \TEX{} warning message because it's not an error message, so \TEX{} doesn't stop running, and it doesn't begin with ``{\tt LaTeX Warning:}''. Below is an alphabetical list of some of \TEX's warnings. \yspace \noindent {\tt Overfull \bs hbox ...}\\ See Section~\ref{line-breaking} on page~\pageref{line-breaking}. \yspace \noindent {\tt Overfull \bs vbox ...}\\ Because it couldn't find a good place for a page \index{page breaking} break, \TEX{} put more on the page than it should. See Section~\ref{page-breaking} on page~\pageref{page-breaking} for how to deal with page-breaking problems. \yspace \noindent {\tt Underfull \bs hbox}\\ Check your output for extra vertical space. If you find some, it was probably caused by a problem with a \xsp{}\verb"\\"\index{!!}\xsp{} or \verb"\newline"\index{!newline} command---for example, having two \xsp{}\verb"\\"\xsp{} commands in succession. This warning can also be caused by inserting a \hbox{\verb"\linebreak"} command. \yspace \noindent {\tt Underfull \bs vbox}\\ See Section~\ref{page-breaking} on page~\pageref{page-breaking}.