Appendix B. Tracing and Resolving Problems

In an ideal world all documents you produced would compile without problems and give high-quality output as intended. If you are that lucky, there will be no need for you to consult this appendix, ever. However, if you run into a problem of some kind, the material in this appendix should help you to resolve your problem easily.

We start with an alphabetical list of all error messages, those after which LaTeX stops and asks for advice. “All” in this context means all LaTeX kernel errors (their text starts with LaTeX Error:), practically all TeX errors (i.e., those directly produced by the underlying engine), and errors from the packages amsmath, babel, docstrip, calc, color, graphics, graphicx, inputenc, fontenc, and textcomp. Errors reported by other packages—those that identify themselves as

where 〈package〉 is not one of the above—are not included. For such errors you should refer to the package description elsewhere in the book or consult the original package documentation.

But even if there are no real errors that stop the processing, warning and information messages might be shown on the terminal or in the transcript file. They are treated in Section B.2, where you will find all LaTeX core messages and all relevant TeX messages that may need your attention, together with an explanation of their possible causes and suggestions on how to deal with them.

The final section deals with tools for tracing problems in case the error or warning information itself is not sufficient or does not exist. We will explore ways to display command definitions and register values, then take a look at diagnosing and solving page-breaking problems. This is followed by suggestions for identifying and solving paragraph-breaking problems. We finish with a description of the trace package, which helps in thoroughly tracing command execution, in case your own definitions or those of others produce unexpected results.

Some of the material in this appendix can be considered “low-level” TeX, something that, to the authors’ knowledge, has never been described in a “LaTeX” book. It is, however, often important information. Directing the reader to books like The TeXbook does not really help, since most of the advice given in books about plain TeX is not applicable to LaTeX or produces subtle errors when used. We therefore try to be as self-contained as possible by offering all relevant information about the underlying TeX engine as far as it makes sense within the LaTeX context.

Finding the source line of an error

Whenever LaTeX starts reading a file, it displays a “(” character that is immediately followed by the file name. Once LaTeX has finished reading the file, it displays the matching “)” character. In addition, whenever it starts preparing to output a page, it displays a “[” character followed by the current page number. Thus, if you see something like

you can deduce that the error happened inside an argument of some command (<argument>) and was detected when LaTeX gathered material for page 7. It got as far as reading most of line 235 in the file ch-1.tex. In this example the error is readily visible in the source line: extsf was misspelled as extss inside the argument to the section command. In some cases, however, the relationship between error and source line is blurred or even nonexistent.

For example, if you define enewcommand hepart{Alp{part}}, then the typo will appear only when you use the part command that executes your definition. In that case you get

In this particular case the actual error is not on line 167 and most likely not even in the current file—the part command merely happens to call the faulty definition of hepart.

Sometimes an error is detected by LaTeX while it is preparing a new page. Since this is an asynchronous operation, the source line listed in the error message is of no value whatsoever. So if you do not understand how the error should be related to the source line, you may well be right—there is, indeed, no relationship. Here is an example:

One way to obtain additional information about an error (or information about how LaTeX intends to deal with it) is to reply 〈h〉 in response to the ? that follows the error message. If used with a TeX error such as the one above, we get

You probably already see the problem with advice coming directly from the TeX engine: you may have to translate it, because it often talks about commands that are not necessarily adequate for LaTeX documents (e.g., for def you should read ewcommand or enewcommand). With real LaTeX errors this is not the case, though here you sometimes get advice that is also not really helpful:

Well, thank you very much, we already knew that! It is, however, worth a try, since there are many messages with more detailed advice.

Displaying the stack of partially expanded macros

Another way to get additional information about an encountered error is to set the counter errorcontextlines to a large positive value. In that case LaTeX will list the stack of the current macro executions:

You read this bottom up: LaTeX has seen the T (lines 15 and 16) but wants to read it again later (<to be read again>, lines 13 and 14) because it switched to the output routine (<output>). There it got as far as executing the command @opcol (lines 11 and 12), which in turn got as far as calling @outputpage (lines 9 and 10), which was executing @thefoot (lines 6 and 7). Line 4 is a bit curious since it refers to @oddfoot rather than @thefoot as one would expect (@thefoot expands to @oddfoot, so it is immediately fully expanded and not put onto the stack of partially expanded macros). Inside @oddfoot we got as far as calling hepage, which in turn expanded to omen (lines 2 and 3), which is finally flagged as an undefined command (line 1).

Fortunately, in most cases it is sufficient only to display the error message and the source line. This is why LaTeX’s default value for errorcontextlines is -1, which means not showing any intermediate context.

Persistent errors

Errors can also occur when LaTeX is processing an intermediate file used to transfer information between two runs (e.g., .aux or .toc files). Data in such files can be corrupted due to an error that happened in a previous run. Even if you have corrected that error in your source, traces of it may still be present in such external files. Therefore, in some cases you may have to delete those files before running LaTeX again, although often the problem vanishes after another run.

Errors due to fragile commands

Common sources for such nasty errors in LaTeX are so-called fragile commands used unprotected in moving arguments. Technically, a moving argument is an argument that is internally expanded by LaTeX without typesetting it directly (e.g., by using the internal LaTeX construct protected@edef¹). But as a rule of thumb you can think of it as an argument that is moved somewhere else before typesetting—for example, the arguments of sectioning commands, such as section (sent to the table of contents), the argument of caption (sent to the list of figures or tables), and the arguments of markboth and markright.

¹ Some people have heard that the TeX primitive edef exists for this purpose. It is not advisable to use it in your own commands, however, unless you know that it will never receive arbitrary document input. You should use protected@edef instead, since that command prevents fragile commands from breaking apart if they are prefixed by protect!

The best, though not very helpful, definition of a fragile command is that it is a command that produces errors if it is not preceded with a protect command when used in a moving argument. Today, most common LaTeX commands have been made robust, so that such protection is not necessary. However, if you get strange errors from a command used in a moving argument, try preceding it with protect. Typically, core LaTeX commands with optional arguments are fragile, but sqrt[3]{-1} is robust and so are all user-defined commands with an optional argument. On the other hand, [... ] is fragile in standard LaTeX, yet it becomes robust once the amsmath package is loaded. In other words, there are no precise rules defining which commands belong to which category. User-defined commands with only mandatory arguments are fragile if they contain any fragile commands in their definition. For example, the definition

is fragile because the comparison argument of ifthenelse is fragile. If you used frail in the @ expression of a tabular (not that this makes much sense),

you would see the following 134 errors before LaTeX finally gives up (the left column displays the number of occurrences):

In fact, in this particular example TeX gets into a loop in which it tries to insert a cr command, immediately rejects its own idea, and then repeats this process.

All TeX errors can be caused by a fragile command in a moving argument!

What we can learn from this example is the following: whenever you encounter a strange TeX error that has no simple explanation (e.g., a misspelled command name), it is possibly due to a fragile command that got broken in a moving argument—so try protecting it with protect at the point where the error occurs. Since this can be the reason behind every TeX error, we shall not repeat this possible cause for every one of them (after all, more than 60 TeX error messages are explained below).

Errors produced by cross-reference keys

As discussed in Section A.1.1, a few restrictions are placed on the characters that can be used in reference key arguments of label and ibitem. In a nutshell, such keys sometimes act like moving arguments and, depending on the combination characters used and the packages loaded, all kinds of dreadful TeX errors may show up. In that case protection with using the protect command will not work; instead, you have to use a simpler key conforming to the syntax restrictions for such keys.

*

If LaTeX stops by just displaying a star, then it has reached the end of your source document without seeing a request to finish the job (i.e., end{document} or stop) and is now waiting for input from the terminal. While this is in itself not an error, in most circumstances it means that something went seriously wrong. If there have been no previous errors and your document finishes with end{document}, then you might have forgotten to close a verbatim environment so that the remainder of the document was processed “verbatim”.

To find the source of this problem in a large document, reply end{foo}, which either should give you an “Environment ... ended by...” error (indicating what environment LaTeX thinks is still open) or will be swallowed without any reaction, in which case you know that you are indeed in some “verbatim” context. In the latter event, try to interrupt LaTeX (by pressing Control-C or whatever your installation requires) and reply with “x” to the “Interruption” error to quit the job. Looking afterwards at the last page in the typeset document usually gives some hint about where things started to go wrong.

'〈character〉' invalid at this point

You loaded the calc package and one of the formulas in setcounter, setlength, addtocounter, or addtolength used a syntax not supported by calc. See Section A.3.1 for details.

〈command〉 allowed only in math mode

This command or environment can be used only in math mode. Check carefully to see what is missing from your document.

〈name〉 undefined

This error is triggered when you use enewcommand for a 〈name〉 that is unknown to LaTeX. Either 〈name〉 was misspelled or you should have used ewcommand instead.

< in mid line

The <, defined within a tabbing environment, was encountered in the middle of a line. It can be used only at the beginning of a line (e.g., after \).

A <Box> was supposed to be here

This error is the result of using a box command, such as sbox, with an invalid first argument (i.e., one not declared with ewsavebox). Usually, you first get the error “Missing number, treated as zero” indicating that TeX uses box register zero.

Accent 〈command〉 not provided by font family 〈name〉

The textcomp package implements the TS1 encoding, which is unfortunately implemented fully by just a minority of the font families usable with LaTeX. No accent will be printed. See Section 7.5.4 for information on how to provide an alternative representation for it.

Argument of 〈command〉 has an extra }

A right brace was used in place of a mandatory command argument (e.g., mbox}). Fragile commands, when used without protect in a moving argument, often break in a way that generates this or one of the other “extra” errors discussed below.

Bad line or vector argument

LaTeX issues this error if you specified a negative length or used an illegal slope with either line or vector. In the latter case, see Chapter 10 for alternatives.

Bad math environment delimiter

This error is triggered when a ( or [ command is encountered inside a formula, or when ) or ] is found in normal text. Check whether these commands are properly matched in your document.

egin{〈env〉} allowed only in paragraph mode

There are many places, such as within LR-mode text or math mode, where it does not make sense to have a math display. With amsmath the whole display 〈env〉 will simply be ignored.

egin{〈env〉} on input line 〈line number〉 ended by end{〈other env〉}

You receive this error when LaTeX detects that the environment 〈env〉 was incorrectly terminated with the end-tag for the environment 〈other env〉. The most likely case is that you, indeed, forgot to close the environment 〈env〉.

Another possible source of this error is trying to use verbatim-like environments or an amsmath display environment inside the definition of your own environments, which is often impossible. See Section 3.4.3 on page 164 for solutions involving verbatim-like environments.

If neither is the case and you are absolutely sure that all environments are properly nested, then somewhere between the start of 〈env〉 and the point where the error was found there must be a command that issues an endgroup without a prior matching egingroup so that LaTeX is fooled into believing that the 〈env〉 environment ended at this point. One way to find that problem is to move the end-tag closer to the begin-tag, until the problem disappears.

egin{split} won't work here

Either this split environment is not within an equation or perhaps you need to use aligned here.

Can be used only in preamble

LaTeX has encountered a command or environment that should be used only inside a package or the preamble (i.e., before egin{document}). This error can also be caused by a second egin{document}.

Cannot be used in preamble

Some commands—for example, ocite—are allowed only in the document body (i.e., after egin{document}). Move the declaration to that point.

Cannot define Unicode char value < 00A0

Values less than "00A0 (decimal 160) are either invalid as Unicode values for text characters or must not be redefined in LaTeX.

Cannot determine size of graphic in 〈file〉

You did not specify an explicit image size on the includegraphics command and LaTeX was unable to determine the image size from the graphics 〈file〉 directly. It usually does this automatically, for example, for .eps files by reading the bounding box information. However, depending on the graphics driver, it may be unable to extract this information from binary bitmap images such as .jpg, .gif, and .png files.

Cannot include graphics of type: 〈ext〉

You will get this error if you have specified a graphics type in the second argument of DeclareGraphicsRule or used the type keyword of includegraphics for which the loaded graphics driver has no support.

caption outside float

A caption command was found outside a float environment, such as a figure or table. This error message is disabled by some of the extension packages described in Chapter 6.

Command 〈name〉 already defined

You try to declare a command, an environment, a new savebox, a length, or a counter with a 〈name〉 that already has a meaning in LaTeX. Your declaration is ignored and you have to choose a different name. This error is also triggered if you use ewcommand with a 〈name〉 starting in end..., even if enewcommand claims the 〈name〉 is unused. It will also be issued if you try to define an environment 〈name〉 but the command end〈name〉 already has a definition. For instance, you cannot define an environment graf because TeX has a low-level command called endgraf.

Command 〈name〉 invalid in math mode

This is either a warning or an error message indicating that you have used a command in math mode that should be used only in normal text. In case of an error message, use h to get further help.

Command 〈name〉 not defined as a math alphabet

This error is issued when you try to use SetMathAlphabet on a 〈name〉 that was not previously declared with DeclareMathAlphabet or DeclareSymbolFontAlphabet to be a math alphabet identifier.

Corrupted NFSS tables

LaTeX tried some font substitution and detected an inconsistency in its internal tables. This error happens if font substitution was triggered and the substitution rules contain a loop (i.e., some circular sub declarations exist) or when the default substitution arguments for the current encoding point to a nonexistent font shape group.

Counter too large

This error is produced if you try to display a counter value with fnsymbol, alph, or Alph and the value is outside the available range for the chosen display form.

Dimension too large

TeX can only deal with absolute sizes that are less than 16383.99998pt (about 226 inches). Even on a huge page this range should be enough.

displaybreak cannot be applied here

An enclosing environment such as split, aligned, or gathered has created an unbreakable block.

Division by 0

Usually, you will get this error when you scale a graphic that has a height of zero. This can happen unintentionally—for example, if you specify angle=-90,height=3cm on includegraphics. The rotation turns the image sideways, making the height zero, a value difficult to scale. In such a case use totalheight instead.

Double subscript

Two subscripts appear in a row (e.g., x_i_2) and LaTeX does not know whether you mean x_i2 or x_i2. Add braces to indicate the subscripts: x_{i_2}.

Double superscript

LaTeX found two superscripts in a row. See the explanation above.

Encoding file '〈name〉' not found

If you ask for encoding 〈enc〉, LaTeX tries to load the definitions for this encoding from the file 〈enc〉 enc.def (after converting 〈enc〉 to lowercase letters). If this encoding file does not exist or cannot be found by LaTeX, you will get this error message.

Encoding scheme 〈name〉 unknown

The encoding scheme 〈name〉 you have specified in a declaration or in fontencoding is not known to the system. Either you forgot to declare it using DeclareFontEncoding or you misspelled its name.

Environment 〈name〉 undefined

You get this error if you use enewenvironment on an environment name that is unknown to LaTeX. Either the 〈name〉 was misspelled or you should have used ewenvironment instead.

Erroneous nesting of equation structures;
trying to recover with ‘aligned’

Only certain amsmath display structures can be nested; aligned is one of these, so the system replaces a wrongly nested environment with it. This is probably not what you intended, so you should change the wrongly nested environment.

Extra & on this line

This error occurs only when you are using old amsmath environments that are not described in this book. If it does occur, then it is disastrous and you need to check very carefully the environment where it occurred.

Extra alignment tab has been changed to cr

If you use an alignment structure, such as tabular or one of the display math environments (e.g., eqnarray or split from the amsmath package), then each row is divided into a defined number of columns separated by & signs. The error means that there are too many such characters, probably because you forgot a \ indicating the end of the row (cr is TeX’s name for the row end, but it is not a fully functional equivalent to \).

Extra endgroup

TeX has seen an endgroup without a preceding matching egingroup.

Extra or

TeX encountered an or primitive that has no matching low-level ifcase conditional. The extra or can be the result from a bad use of ifthenelse.

Extra ight

This error is issued by TeX if it finds a ight command without a matching left in a formula. Recall that left/ ight pairs must be part of the same “sub-formula”. They cannot, for example, be separated by & in an alignment or appear on different grouping levels.

Extra }, or forgotten $

This error is triggered when math formula delimiters (e.g., $...$, [...]) and brace groups are not properly nested. TeX thinks it has found a superfluous }, as in $x}$, and is going to ignore it. While in this example the deletion of the closing brace is the right choice, it would be wrong in mbox{(a}. There a closing ) is missing, so deleting the } will produce additional errors.

Extra }, or forgotten endgroup

The current group was started with egingroup (used, for example, by egin{..}) but TeX found a closing } instead of the corresponding endgroup. You will get this error if you leave a stray } inside a body of an environment.

File '〈name〉' not found

LaTeX is trying to load the file 〈name〉 but cannot find it, either because it does not exist or because the underlying TeX program is looking in the wrong place. If the file exists but LaTeX claims it is not available, it is possible that your TeX installation uses a hashing mechanism to speed up file access, and you may have to run a special program to make your installation aware of newly installed files (e.g., mktexlsr with the TeX Live distribution on the CD-ROM).

The error is issued by commands like input and usepackage if they cannot find the requested file. You can suggest an alternate file in response to the error. If the new name is specified without an extension, the old extension is reused if known to LaTeX. If you want to omit loading the file, press 〈Enter〉; to quit the run, type x or X. In some cases you might receive a similar low-level TeX error “! I can’t find file ‘〈name〉’” that is slightly more difficult to quit; see the entry on page 901.

If a graphics file requested with includegraphics is missing, it may help to press h to learn which extensions have been tried when looking for the file.

File ended while scanning 〈something〉

This error is part of a “Runaway...” error; check the explanations on page 909.

Float(s) lost

One or more floats (e.g., figure or table) or marginpar commands have not been typeset. The most likely reason is that you placed a float environment or marginal note inside a box by mistake—inside another float or marginpar, or inside a minipage environment, a parbox, or a footnote. LaTeX might detect this problem very late, such as when finishing the document. This can make it very difficult to find the offending place in the source. The best solution in this case is to half your document repeatedly (for example, by using the primitive endinput), until the fraction producing the error is small enough that you spot it.

If incorrect nesting is not the root cause, then you may have encountered a serious coding problem in the float algorithm, probably caused by some extra packages you loaded.

Font family 〈cdp〉 + 〈family〉 unknown

You tried to declare a font shape group with DeclareFontShape without first declaring the font 〈family〉 as being available in the encoding 〈cdp〉 using DeclareFontFamily.

Font 〈name〉 not found

LaTeX’s internal font tables contain wrong information, so LaTeX was unable to find the external font 〈name〉. Either this font was never installed, its .tfm file cannot be found by TeX for some reason, or the DeclareFontShape declaration referring to it contains a spelling error.

Font 〈internal-name〉 = 〈external-name〉 not loadable: 〈reason〉

TeX was unable to load a font with the LaTeX name 〈internal-name〉 having the structure 〈encoding〉 / 〈family〉 / 〈series〉 / 〈shape〉 / 〈size〉 in NFSS notation.¹ For example, it might say T1/cmr/m/it/10 (Computer Modern medium italic 10 points in T1 encoding). This should give you a good hint as to which font has a problem, even if you are not able to do much about it. There are two possible 〈reason〉 s:

¹ This is, in fact, a single command name, but due to the slashes in the name you cannot enter it directly in your document.

Bad metric (TFM) file

The TeX metric file for the font (i.e., 〈external-name〉 .tfm) is corrupted. Your installation may have some utility programs to check .tfm files in detail, although this usually requires expert help.

Metric (TFM) file not found

The TeX metric file for the font (i.e., 〈external-name〉 .tfm) was not found. Your installation may have a package (e.g., cmbright) to support a certain font family but the corresponding fonts are not available or are not properly installed.

Font 〈internal-name〉 = 〈external〉 not loaded: Not enough room left

TeX can load only a certain number of fonts and there was no space left to load 〈internal-name〉. To find out which fonts are loaded, use the package tracefnt described in Section 7.5.6. One possible reason for excessive loading of fonts is the use of unusual font sizes for which LaTeX has to calculate and load the corresponding math fonts; see Section 7.10.7 for details.

Font shape 〈font shape〉 not found

This error message is issued when there is something very wrong with a DeclareFontShape declaration—perhaps if it does not contain any size specifications. Check the set-up for the font shape group in question.

I can't find file '〈name〉'

A low-level TeX error raised when TeX cannot find a file that was requested to load. This error can be bypassed only by providing TeX with a file that it can find, or by stopping the run altogether (if your operating system allows that). To get past this error, many installations offer a file null.tex so that you can reply null in response. LaTeX normally uses the error message “File ‘〈name〉’ not found”, which supports various user actions. However, depending on the package coding, you may get the current error instead.

I can't write on file '〈name〉'

TeX is not allowed to write data to the file 〈name〉. It is probably read-only or you may not have writing permission for its directory. On some TeX implementations (e.g., those on the TeX Live CD), the error may be preceded by a line like the following:

These TeX installations are by default configured to be “paranoid” (hence, “p” above) when writing to files. They allow you to write only to files below the current directory and not to any files specified with an absolute path name or starting with a dot in their name. To change that behavior you have to modify the settings in the file texmf.cnf.

Illegal character in array arg

You will get this error if the column specification for a tabular or array environment or a multicolumn command contains characters that are not defined as column specifiers to LaTeX. A likely cause is that you used the extended syntax of the array package, described in Chapter 5, but forgot to load the package in the preamble (e.g., after you have copied a table from one document to another).

Illegal parameter number in definition of 〈command〉

This error occurs when a (re)defined command or environment uses # 〈digit〉 in the replacement text, with a digit higher than the declared number of parameters. This error can be implicitly caused by nesting declaration commands, such as ewcommand, and forgetting that inner commands refer to their arguments by doubling the # characters; see page 846 for details. Another possible cause is referring to environment arguments in the second mandatory argument of ewenvironment or enewenvironment.

Illegal unit of measure (pt inserted)

You will get this error if you misspell or forget the unit when specifying the value for a length parameter; see Section A.1.5.

Improper argument for math accent:                        
Extra braces must be added to prevent wrong output

The whole of the “accented sub-formula” must be surrounded by braces.

Improper discretionary list

This error is produced by TeX if it encounters a discretionary command whose arguments contain anything other than characters, boxes, or kerns, after expansion.

Improper hyphenation

If you want to specify a hyphenation exception with hyphenation, then you have to ensure that the argument contains only letters and - characters to indicate the hyphenation points. The problem is that, for example, accented characters in some font encodings are individual glyphs (allowed) but in other font encodings produce complicated constructs requiring the accent primitive. For example, if the T1 encoding is used, then "u refers to a single glyph. Thus,

is valid. The same hyphenation exception used with the default OT1 encoding would produce this error. See page 455 for an explanation of character differences in the major encodings.

Improper prevdepth

You used heprevdepth or showtheprevdepth outside of vertical mode, which is not allowed. This error will also show up if you mistakenly placed a float (e.g., a figure or table) inside a math display environment.

Improper spacefactor

You used hespacefactor or showthespacefactor outside of horizontal mode, which is not allowed.

include cannot be nested

LaTeX encountered an include command inside a file loaded with include. Because of implementation constraints this is impossible. Either change the inner include into input or rearrange your document file structure so that all include statements are in the main document file.

Incompatible list can't be unboxed

TeX was asked to unpack a box with horizontal material while trying to build a vertical list, or vice versa. Either you encountered a serious programming error in a package or you used some commands in a way explicitly not supported. For example, the commands from the soul package will produce this error when they are nested into each other.

Incomplete 〈conditional〉 ; all text was ignored after line 〈number〉

A low-level TeX conditional was unfinished (no matching fi) when LaTeX reached the end of the current input file.

Infinite glue shrinkage found 〈somewhere〉

To break paragraphs into lines or the galley into pages, TeX assumes that there is no rubber length that can arbitrarily shrink, since that would mean that any amount of material can be placed into a single line or onto a single page. Thus, hspace{0pt minus 1fil} in a paragraph, or vspace{0pt minus 1fil} between paragraphs is not allowed and will raise this error (〈somewhere〉 gives some indication about where the offending material was found).

Interruption

You will get this error after interrupting the LaTeX run (with Control-C or whatever your installation offers), so you should not be surprised by it. To finish the run prematurely, press x followed by 〈Return〉. Just pressing 〈Return〉 will continue the run.

Invalid use of 〈command〉

You have used an amsmath command in a place where it does not make sense. Look up the correct use of this command.

Keyboard character used is undefined in input encoding 〈name〉

The 8-bit number encountered in the document is not mapped by the input encoding 〈name〉 to some LICR object (see Sections 7.5.2 and 7.11.3). Check whether the document is really stored in the specified encoding.

Language definition file 〈language〉 .ldf not found

When LaTeX processes the option list for babel and encounters an unknown option 〈language〉, it tries to load a file by the name of 〈language〉 .ldf. This message is displayed when LaTeX fails to find it. This error can be caused by a simple typing mistake, or the file might not be stored on LaTeX’s search path.

Limit controls must follow a math operator

You can use limits or olimits only following math operators such as sum. See Table 8.4 for a list of common operator commands.

LoadClass in package file

The LoadClass command is only allowed in class files; see Section A.4.

Lonely item—perhaps a missing list environment

The item command is only allowed within list structures but LaTeX believes that this one was found outside a list.¹

¹ In contrast to the “... perhaps a missing item” error, LaTeX’s diagnosis in this case is usually correct.

Math alphabet identifier 〈id〉 is undefined in math version 〈name〉

The math alphabet identifier 〈id〉 was used in a math version (〈name〉) for which it was not set up. An additional SetMathAlphabet declaration should be added to the preamble of the document to assign a font shape group for this alphabet identifier.

Math version 〈name〉 is not defined

A math alphabet or a symbol font was assigned to a math version that is unknown to LaTeX. Either you misspelled its name or you forgot to declare this version (perhaps you have to add some package file). It is also possible that the math version you selected with mathversion is not known to the system.

Misplaced alignment tab character &

LaTeX found an & character outside of tabular, align, or one of the other alignment environments. If you want to typeset &, use & instead. A possible cause is use of the amsmath environment cases or matrix without loading the package.

Misplaced cr or Misplaced crcr

A cr is the TeX low-level command for ending a row in an alignment structure (crcr is a variation thereof); the corresponding LaTeX command is \. TeX believes it came across such a command outside of an alignment structure.

Misplaced oalign

The TeX primitive oalign is internally used to place “nonaligned” material between rows of alignment displays. It is therefore allowed only directly following the command that finishes a row. For example, you get this error when you use hline outside of array or tabular, or not directly after \ within these environments.

Misplaced omit

The TeX primitive omit is internally used to change the column specifications in an alignment display (e.g., to span rows with multicolumn inside a tabular). The omit command (and thus the commands calling it) is allowed only at the very beginning of an alignment cell (i.e., following \ or &).

Missing egin{document}

This error occurs if typesetting is attempted while still within the document preamble.¹ It is most likely due to a declaration error that is misinterpreted by LaTeX. The error is also produced by text following egin{filecontents} on the same line.

¹ Typesetting inside an sbox or savebox declaration is accepted, but it is usually wise to move such declarations after egin{document}, since some packages may delay their final set-up until that point.

Missing control sequence inserted

You used ewcommand or enewcommand without providing a command name (starting with a backslash) as the first argument.

Missing cr inserted

TeX thinks it is about time to end the row in an alignment structure and inserted its low-level command for this purpose. In a LaTeX document, this guess is usually wrong, so TeX’s recovery attempt usually fails in such a case.

Missing delimiter (. inserted)

A left, ight, or one of the ig.. commands was not followed by a delimiter. As corrective action the empty delimiter “.” was inserted. See Section 8.5.3 on page 498 for details.

Missing endcsname inserted

This error can arise from using commands as part of the name of a counter or environment (e.g., ewenvironment{Bl"ode}).

Missing number, treated as zero

This error occurs when TeX is looking for a number or a dimension but finds something else. For example, using value{page} instead of hepage would produce this error, since an isolated value makes TeX expect a low-level counter assignment. In general, using a length register without a proper mutator function like setlength can trigger this error. You also get this message when usebox is not followed by a box bin defined with ewsavebox, since internally such bins are represented by numbers.

Missing p-arg in array arg

There is a p column specifier not followed by an expression in braces (containing the width) in the argument to tabular, array, or multicolumn.

Missing @-exp in array arg

There is an @ column specifier not followed by an expression in braces (containing the inter-column material) in the argument to tabular, array, or multicolumn.

Missing # inserted in alignment preamble

An alignment preamble specifies the layout of the columns in an alignment structure. Internally, TeX uses # to denote the part of the column that should receive input. In LaTeX this is unlikely to appear as a first error.

Missing = inserted for ifnum

TeX complains that the low-level ifnum conditional is not followed by two numbers separated by <, =, or >. This error can occur when you forget the comparison operator in ifthenelse.

Missing = inserted for ifdim

The low-level ifdim conditional is not followed by a comparison between two lengths.

Missing $ inserted

TeX has encountered something in normal text that is allowed only in math mode (e.g., sum, alpha, ^), or something that is not allowed inside math (e.g., par) while processing a formula. It has therefore inserted a $ to switch to math mode or to leave it. If, for example, you tried to get an underscore by simply using _ instead of \_, LaTeX would typeset the rest of the paragraph as a formula, most likely producing more errors along the way.

Missing endgroup inserted

This error indicates that a grouping structure in the document is incorrectly nested. Environments internally use egingroup and endgroup and for some reason TeX thinks that such a group was not properly closed. If you cannot determine why the group structure is faulty, try using the showgroups or racinggroups feature of eTeX, as explained on page 917.

Missing ight. inserted

Your formula contains a left without a matching ight. Recall that left/ ight delimiter pairs must be part of the same “sub-formula”; they cannot, for example, be separated by & in an alignment or appear on different grouping levels.

Missing { inserted

TeX thinks there is an open brace missing and inserted one. This error is, for example, caused by a stray } inside a tabular cell.

Missing } inserted

Something is wrong in the grouping structure of the document and TeX tries to recover by inserting a closing brace. This attempt either gets it onto the right track again or causes you to receive more errors. Usually, the problem becomes apparent if you look at the typeset output. If you cannot determine why the group structure is faulty, try using the showgroups or racinggroups feature of eTeX, as explained on page 917.

Multiple label's: label 〈label〉 will be lost

Within the amsmath display environments, you can have only one label per equation. It is usually best to remove all but the last, as it is the only one that will be effective.

Multiple ag

Within the amsmath display environments, you can have only one ag command per equation. All but the first will be ignored.

No counter '〈name〉' defined

The counter 〈name〉 referenced in either setcounter, addtocounter, or the optional argument of ewcounter or ewtheorem is unknown to LaTeX. It must first be declared with ewcounter.

No Cyrillic encoding definition files were found

The language definition files for the supported “Cyrillic languages” check whether any of the known Cyrillic font encoding files (e.g., T2A, T2B) can be found. If not, this error message is displayed and you need to install Cyrillic support for LaTeX first.

No declaration for shape 〈font shape〉

The sub or ssub size function used in a DeclareFontShape command refers to a substitution shape that is unknown to LaTeX’s font selection scheme.

No driver specified

The package graphics, graphicx, or color was loaded without specifying a target device option. On most installations this is done using the configuration files graphics.cfg and color.cfg.

No room for a new 〈register〉

The packages loaded in your document require more internal registers (count, dimen, ...) than there are available in TeX. Try processing your document with eTeX and additionally load the etex package.

No itle given

A LaTeX class has executed maketitle without seeing a itle declaration. Only date is optional when this command is used.

Not a letter

You specified a hyphenation exception with hyphenation but the argument to this command contained some characters that TeX does not consider to be letters. For example, hyphenation{la-ryn-gol-o-gist's} would produce such an error since ' is not a “letter” in TeX’s categorization.

Not in outer par mode

This error is issued when a marginpar or a float environment, such as table or figure, is encountered inside a box-producing command or environment. For instance, you cannot use a marginpar in a footnote, a float, a tabular, or a similar place (since all of them produce boxes). Move the offending object to the main galley.

Number too big

You assigned or used a number in setcounter or addtocounter that is larger than the largest number that TeX can handle (2147483647, hexadecimal 7FFFFFFF). This error can also happen when modifying a length register with setlength or addtolength.

OK

You used a TeX tracing command, like show or showthe; after displaying the data LaTeX stopped with this message to allow for some interaction on the command line (e.g., entering ishow.. to view some other values). This message is also shown if racingonline is positive and commands are used that normally only write to the transcript file; see the next message.

OK (see the transcript file)

You used a TeX tracing command, like showbox or showlists, without also directing LaTeX to display the result on the terminal.

Old form 〈command〉 should be egin{〈envname〉}

You have used cases, matrix, or pmatrix in its non-amsmath command form (probably with its old internal syntax). Change to the amsmath environment form with standard internal syntax.

Only one # is allowed per tab

This error indicates a broken alignment template. In LaTeX it should not occur, unless caused by a fragile command in a moving argument.

Option clash for package 〈name〉

The package 〈name〉 was requested twice with a conflicting set of options. When you press H in response to this error, LaTeX will show you the sets of conflicting options. As LaTeX loads a package only once,¹ the best solution is to specify all options on the first occasion. If this is not possible, because the package is already loaded as part of the class or another package, you can try to specify the required options as global options to the documentclass command. In an emergency you can even load a package before documentclass by using RequirePackage. See Section 2.1.1 for details.

¹ The only exception is the fontenc package, which can be loaded as often as needed with different options; see Section 7.5.3 on page 361.

Page height already too large

You used enlargethispage on a page whose vertical size is already larger than 8191.99998pt, or roughly 113 inches. LaTeX thinks that this is dangerously large and will not extend the page size as requested.

Paragraph ended before 〈command〉 was complete

As discussed in Section A.1.2, commands defined with ewcommand* or enewcommand* are not allowed to contain par or an empty line. If they do, you will get a Runaway argument together with this error. The 〈command〉 listed may not be the one used in your document. For example, emph{..par..} will list ext@command in the error message (i.e., the internal command called by emph).

(Please type a command or say 'end')

You have replied with 〈Return〉 in response to *. See first entry on page 894.

pushtabs and poptabs don't match

You issued a poptabs command in a tabbing environment, but there was no previous pushtabs command issued.

RequirePackage or LoadClass in Options Section

A RequirePackage or LoadClass was found inside a package or class file between the DeclareOption commands and ProcessOptions. Loading packages or classes in this part is not allowed as it would clobber the data structure holding the current set of options; see Section A.4 for details. If you want to load a package when a certain option is specified, use a flag to indicate that the option was selected and load it after the ProcessOptions command has done its job.

Rotation not supported

You have requested rotation with otatebox or a similar command but the selected graphics driver does not support rotation of objects. LaTeX will leave the right amount of space but the printed document might show the image in the wrong position.

Runaway 〈something〉

TeX thinks it has scanned too far while looking for the end of 〈something〉, where 〈something〉 can be either argument, definition, preamble, or text. Unless low-level TeX code is at fault, the most likely cause is argument. For example, you forgot the closing brace of an argument, it might cause TeX to scan until it reaches the end of the file or until its memory is filled—whichever comes first. Incomplete definitions done with ewcommand, ewenvironment, and so forth also claim that the argument has run away. Only low-level definitions, involving TeX primitives like def, produce a Runaway definition.

A Runaway preamble means that an alignment structure has problems (that should not occur in normal LaTeX documents) and Runaway text usually refers to a token register assignment (this should never happen unless there is a serious package implementation error).

In contrast to the situation with normal error messages, you will not get a line number that indicates where the error was detected (since TeX often has reached the end of the file). Instead, you will see the beginning of the material that was being absorbed. For example, if you have a definition without the final closing brace,

you will get

The fact that TeX in that case inserted par as a recovery action is of little help, since the complete document was already swallowed. Instead of “File ended while...”, you might see some other message at this point, such as “Paragraph ended before...”.

Scaling not supported

You have requested scaling with esizebox or a similar command but the selected graphics driver does not support scaling of objects. LaTeX will leave the right amount of space but the printed document will show the image at the original (unscaled) size.

Something's wrong–perhaps a missing item

This error message is produced by an addvspace command when encountered in horizontal mode. The follow-up remark about “perhaps a missing item” is unfortunately seldom correct. For example, forgetting the closing brace on mbox as in mbox{...section{..}... would produce this error, since the section command that executes addvspace internally is now used in horizontal mode.

Identify which command issued the addvspace causing the error, and check whether that command was used incorrectly. Refer to page 858 for an in-depth discussion of the addvspace command.

Sorry, I can't find 〈format〉 ...

If you get this message, then LaTeX never started because TeX did not find the 〈format〉 containing the basic LaTeX definitions. There is a problem with your TeX installation and you have to consult the installation documentation.

Suggested extra height (〈value〉 ) dangerously large

Using the 〈value〉 with enlargethispage would make the resulting page too large (more than 113 inches) for LaTeX’s liking.

Symbol font 〈name〉 is not defined

You tried to make use of the symbol font 〈name〉—for example, within a DeclareMathSymbol command—without declaring it first with a DeclareSymbolFont declaration.

Symbol 〈command〉 not provided by font family 〈name〉

The textcomp package implements the TS1 encoding, which is unfortunately implemented fully by just a minority of the font families usable with LaTeX. The package will typeset the symbol using a default family stored in extcompsubstdefault. You can turn the error into a warning by loading textcomp with the option warn. See Section 7.5.4 for more details.

Tab overflow

LaTeX supports up to 13 tabulator positions (=) inside a tabbing environment, and you have used a larger number. If not all of them are needed at the same time, you can try solving the problem by using pushtabs and/or providing template lines with kill.

ag not allowed here

The ag command is allowed only within the top level of a mathematical display. It is usually best to move it to the end of the logical equation in which it occurs.

TeX capacity exceeded, 〈explanation〉

TeX ran out of some sort of memory and died. This error is discussed in detail in Section B.1.1 on page 915.

Text line contains an invalid character

The input file contains a strange, nonprinting character that is rejected by TeX. This may happen if you used a word processor to create the file and did not save it as “text”.

The attribute 〈attrib〉 is unknown for language 〈lang〉

You tried to activate an attribute for a language 〈lang〉 that is not defined in the language definition file for this language. Check the documentation of babel with respect to this language.

The character '〈char〉' is not a shorthand character in 〈language〉

When a user uses the command shorthandon and passes it a 〈char〉 that is not defined to be a shorthand for the current 〈language〉, this error message is displayed and the instruction is ignored.

The font size command ormalsize is not defined...

A class file needs to provide a minimal set-up, including a definition for ormalsize; see Section A.4.9 on page 888 for details.

There's no line here to end

This error is triggered if ewline or \ is found outside a paragraph (i.e., after a par or an empty line). If the intention was to produce extra vertical space, use vspace or any of the other commands described on page 857.

This may be a LaTeX bug

To the author’s knowledge, until now this message never actually signaled a LaTeX bug. It means, however, that LaTeX got thoroughly confused by previous errors and lost track of the state of its float data structure. It is best to stop and correct previous errors first.

This NFSS system isn't set up properly

This error occurs when LaTeX detects a mistake while trying to verify the font substitution tables at egin{document}. It means that either a DeclareFontSubstitution or DeclareErrorFont¹ declaration is corrupted. These declarations need to point to valid font shapes (declared with DeclareFontShape). Type h for additional information and inform your system maintainer. If you are the system maintainer, read the end of Section 7.10.5.

¹ The declaration DeclareErrorFont is used during installation and points to a font (font shape + size) that should be used when everything else fails. Its default is Computer Modern Roman 10pt, which should be available with any TeX installation. See [109] for further details.

Too deeply nested

Standard LaTeX supports a total of six levels of lists nested in each other. Those levels can include up to four lists of type itemize or enumerate. This error signals that your document has overflowed one of these limits. You probably have forgotten to end some list environments properly. If you really need additional levels, you need to copy the base definitions for list, itemize, and/or enumerate into a private package and modify their hard-wired constants.

Too many columns in eqnarray environment

The eqnarray environment supports a maximum of three columns (i.e., two & signs per row). For serious math, consider the amsmath package described in Chapter 8, which allows for more complex display structures.

Too many math alphabets used in version 〈name〉

You used too many different math alphabet identifiers in your formulas. If this error occurs after adding the bm package, define ewcommandmmax{0} before loading bm and try again; this prevents the package from preallocating math alphabets.

Too many unprocessed floats

Floats that cannot be placed immediately are deferred by LaTeX, possibly causing subsequent floats to be deferred as well. LaTeX can defer up to 18 floats, then you will receive this error message. Using the package morefloats will increase this limit to 36 but if there is a float that cannot be placed for some reason this change will merely delay receiving the above error. See Chapter 6 for ways to deal with this situation.

This error can also be triggered if you have too many marginpar commands within a single paragraph. A marginpar temporarily uses two storage bins for deferred floats as long as the current paragraph has not been typeset (this allows a maximum of nine marginal notes per paragraph, or fewer if there are already some deferred floats).

Two documentclass or documentstyle commands

Only one such command is allowed per document. Your document includes more than one, perhaps as the result of combining two originally separate documents.

Two LoadClass commands

A class can load at most one other class to do the bulk of processing. See Section A.4 for a detailed discussion of how classes are built.

Undefined color 〈name〉

You have requested a color with color or a similar command from the color package without previously defining it with definecolor. See [57] or the color package documentation for details.

Undefined control sequence

This is perhaps the most common of all LaTeX errors, though it shows up as a TeX error message: you have used a command name that was not previously defined. Often you may have simply mistyped the name in your document (e.g., mox instead of mbox). To carry on in such a case, you can respond with imbox, inserting the correct name. Later on you can correct your source document. It is also possible to get this error as a result of using a fragile command in a moving argument.

Undefined font size function 〈name〉

A size function used in DeclareFontShape was misspelled. Check the entry or tell your system maintainer.

Undefined tab position

This error is raised if you try to advance in a tabbing environment with >, +, -, or < to a tabulator position that was not previously set up with =. Either the = is actually missing or perhaps you have used + or pushtabs and got confused when specifying the tabular position to which you actually want to move.

Unknown graphics extension: 〈ext〉

You will get this error if you try to load a fully specified graphics file (with extension 〈ext〉) and the graphics driver does not know the particular extension and there is no default rule set up. The dvips program, for example, interprets every unknown extension as EPS, so with this driver you will never see this error but probably others.

Unknown option '〈option〉' for package '〈name〉'

You specified an 〈option〉 for package 〈name〉 that is not declared by that package. Consult the package documentation on the available options.

Use of 〈command〉 doesn't match its definition

Low-level macro definitions made with def, instead of ewcommand and friends, sometimes require special argument delimiters (e.g., the (..) of the picture commands). If 〈command〉 is a LaTeX command, check its syntax. Otherwise, this is most likely a spurious error due to using a fragile command in a moving argument without protect.

usepackage before documentclass

The usepackage declaration can be used only after the main class was loaded with documentclass. Inside a class file you instead have to use RequirePackage.¹

¹ It is technically possible to load a package before a class by using RequirePackage, but this should be avoided unless you know what you are doing.

UTF-8 string u8: 〈8-bit-sequence〉 not set up for LaTeX use

The Unicode character denoted by the UTF-8 〈8-bit-sequence〉 is not known to LaTeX. Under the precondition that it is available in a font encoding used in the document, it has to be set up using the DeclareUnicodeCharacter declaration; see Section 7.11.3 on page 443.

verb ended by end of line

To better detect errors, the argument of verb must be placed on a single line. Thus, this error signals that you either forgot the final delimiter for the argument or the argument was broken over several lines in the source. In case of very long arguments, it may help to split them over several verb commands and, if necessary, masking a line break in the source with a % sign.

verb illegal in command argument

Except in very special situations (explicitly documented in this book), it is not possible to use verb (or verbatim) in the argument of other commands. If you need verbatim text in such a place, use, for example, SaveVerb and UseVerb from the fancyvrb package described in Section 3.4.3.

You already have nine parameters

LaTeX supports command or environment definitions with a maximum of nine parameters, but your ewcommand or ewenvironment specified 10 or more.

You can't use 'macro parameter #' in 〈some〉 mode

TeX found a stray # character somewhere that does not seem to be a reference to an argument of some command. If you wanted to typeset this symbol, use # instead.

You can't use 'spacefactor' in vertical mode

TeX lets you refer to the spacefactor only when you are building a horizontal list. You will get this error when you use the LaTeX command @ outside of a paragraph. Since many internal commands start with an @ in their names, you might also get this error if you use code containing such internal commands (e.g., @startsection) in the preamble of your document without surrounding it with makeatletter and makeatother. In that case TeX sees @ followed by the letters startsection, and a later use of this code then executes @ that in turn produces this error message.

You can't use 'prevdepth' in horizontal mode

The prevdepth dimension can be used only while in vertical mode (i.e., between paragraphs).

You can't use 'end' in internal vertical mode

This is one of the more misleading TeX error messages, since it refers to the TeX primitive end (ending a TeX run) that was redefined by LaTeX to become the end-tag of environments. The error means that LaTeX’s end{document} or the stop command was encountered while LaTeX was building a box. For example, egin{figure}...stop would generate it.

You can't use '〈command〉' in 〈some〉 mode

TeX complains that 〈command〉 is not allowed in one of its modes. Some specific variations of this theme have already been discussed. If you haven’t used 〈command〉 directly, then the most likely cause for this error is a broken fragile command in a moving argument.

You haven't defined output directory for '〈path〉'

The configuration file docstrip.cfg contains a declaration for BaseDirectory but the internal 〈path〉 in the DOCSTRIP script has no translation to a local directory. Use DeclareDirectory or UseTDS in docstrip.cfg to specify a translation as described in Section 14.2.3 on page 830.

You haven't defined the language 〈language〉 yet

Various user interface commands of babel check whether their argument is a language that was specified in the option list when babel was loaded. If the 〈language〉 was not specified, processing is stopped and this error message is displayed.

You haven't specified a language option

This message is shown when no known languages have been specified for babel—that is, neither in the option list to babel nor in the global option list (this is likely to be due to a typo). You should expect that processing your document will nevertheless produce many more errors.

Until the mid-1990s, memory problems could, in fact, be due to the size of the document. In some cases it was impossible to process a document as a whole.¹ These days such limitations are gone or are at least less severe. For one, the average TeX implementation is already equipped with huge internal tables. In addition, most implementations allow you to modify the table sizes via configuration files instead of requiring you to manually recompile TeX. In some cases you may have to generate a new LaTeX format; for more details, consult the documentation of your TeX distribution.²

¹ The first edition of this book required a specially compiled version of the TeX program with all such tables enlarged by a factor of 10 and could be processed only on a large UN*X workstation.

² The TeX live distribution, which comes with this book, lets you specify the size of most tables through the configuration file texmf.cnf. See the TeX live manual for details.

Nevertheless, people experience this dreadful error once in a while, usually as the result of a faulty command definition. Below are four candidates reduced to the bare bones of the problem we want to discuss—in reality, such problems usually lurk in more complex definitions.

If you execute FAILa as defined above, you will receive the following output (the reported memory size possibly differs) after a short while:

The main memory is the part of TeX in which macro definitions and the material for the current page are stored. Looking at the above recursive definition, it is clear that it generates a never-ending sequence of periods. Since paragraph breaking is deferred until TeX sees a par command or a blank line to globally optimize the line breaks, TeX waits in vain for a chance to break the paragraph material into lines.

Exceeding main memory because of too many macro definitions is less likely these days. Nevertheless, even that can happen (in theory) if the size of this memory is small and you load many packages, have a large number of huge deferred floats, or use macro packages¹ that produce new macros on the fly.

¹ For example, varioref defines two labels internally for every use of vref, which can result in a noticeable amount of memory consumption in large documents.

If you get this error only with larger documents and LaTeX actually produces pages before giving up, you can try to find out whether the memory is gradually filling up (which suggests a table size problem) by setting racingstats=2 in the preamble of your document. TeX will then report the main memory status after finishing each page, producing output like the following:

The number reported to the left of the & is the memory devoted to large objects such as boxes; the number on the right is the amount of memory used by macro definitions and character data. Thus, one can expect a reduction in both values whenever a page has finished (i.e., the after: value). If the right-hand value is slowly increasing, however, then something is probably adding more and more definitions.

If we use FAILb, we overflow a different table. Here the recursion happens before LaTeX actually reaches the end on the macro expansion and thus needs to store away the unprocessed part of the expansion.

With today’s size for the input stack, this message usually appears only if a recursion like the one above makes that stack grow at a frightening speed. In a normal LaTeX document you will seldom find nested definitions that make this stack grow beyond a value of 50 (for this book the maximum value was 35).

What happens if you execute either FAILc or FAILd? Both are similar to FAILa but neither overflows any internal TeX table. Instead, both will simply fill your hard disk. The only action of FAILc is to show periods on your screen and in the transcript file, thereby very slowly filling up the disk with a huge transcript. FAILd, on the other hand, contains a par in its definition and therefore is able to typeset paragraphs (each consisting of a single dot); as a result it produces pages in rapid succession. Such an experiment ended on the author’s machine with a document containing 22279 pages and the following message:

On your private machine, this is merely a nuisance, easily rectified. On systems with shared resources, however, you should be careful when letting LaTeX run unattended. This type of error once hit a student very badly; this individual processed such a document on a mainframe in batch mode without a time or size limit and was presented a bill for computer processing time of several thousand dollars.

Several other internal tables can overflow in principle. Below is the complete list of those not already discussed, along with an explanation for the most likely reason for the overflow. Some additional information can be found in [82, p.300].

buffer size The characters in the lines being read from a file. Since the default size is usually quite large, the most likely cause for an overflow is lost line breaks due to a faulty conversion of a file during transfer from one operating system to another. A buffer overflow can also be caused by some PC word processing programs, which internally put an entire paragraph on a single line even though the text appears to be broken into several lines on the screen.

exception dictionary The number of hyphenation exceptions as specified by hyphenation. LaTeX has some exceptions specified for the English language, and some language packages specify additional exceptions. However, if this table overflows, you must have been doing a very thorough job.

font memory The font metric data loaded by LaTeX. These days an overflow is unlikely. If it happens, LaTeX has loaded too many fonts—probably because you used many different font sizes and LaTeX calculated and loaded math fonts for all the sizes. Increase the table size, if possible, or refer to Chapter 7 for information on how to reduce the number of fonts.

grouping levels The number of unfinished groups that delimit the scope for setting parameters, definitions, and other items—for instance, braces, the start of environments, or math mode delimiters. An overflow usually indicates a programming error (e.g., a definition that opens more groups than it closes). That type of error is sometimes difficult to identify. Good help is available with the eTeX program,¹ which offers the command showgroups to produce a listing of stacked groups starting with the innermost one. For example, placing it into the footnote on the current page will yield

¹ In modern distributions LaTeX is automatically using the eTeX program. On older installations you may have to call a different program (e.g., eLaTeX instead of LaTeX) when processing a document.

The semi simple group on level 1 is due to the fact that this text is typeset in a description environment (the egin command issues internally a egingroup command). The footnote command is implemented with the TeX primitive insert, which contributes level 2. In fact, another semi simple group is started by footnote, which ensures that color changes remain local. What we can deduce from this example is that the relationships among top-level document commands and internal groups are far from obvious or simple. However, the line numbers that show when a group was entered do help, since there are usually no long-ranging groups in normal documents.

As an alternative, the eTeX program offers the internal tracing counter racinggroups. If it is set to a positive number, the entry and exit of groups is recorded in the transcript file; with racingonline having a positive value, this information also appears on screen.

hash size The number of command names known to TeX. Most packages contribute a fixed number of new command names. Each label or ibitem command in the document generates one new internal command name. Thus, packages that internally use the label command (e.g., varioref) may significantly contribute to filling that table in large documents.

number of strings The number of strings—command names, file names, and built-in error messages—remembered by TeX. In some cases TeX is able to free unused space but usually such strings survive even if they are used only locally. One possible reason for overflowing this table is the use of many files in an application. Each opening for reading or writing of a file contributes, even when the same file is used many times over.

For historical reasons, TeX has a somewhat unusual string-handling concept involving several tables, each of which can overflow. Thus, if you change the hash size to allow for more commands, you may need to adjust the number of strings and quite likely the pool size, and vice versa.

parameter stack size The total number of command parameters of nested commands being expanded but not yet fully processed. For example, suppose a command with 4 arguments calls a command with 5 arguments, which in turn calls a command with 3 arguments, thereby using up 12 slots in this table. The moment TeX reaches the end of a macro replacement text it will free the stack. Thus, with today’s implementations it is quite difficult to hit that limit, unless you use a flaky recursive definition with arguments, for example:

Do you see the problem? Since the ypeout contains FAIL by mistake, it gets called again, before its replacement text has been fully processed (picking up the characters i, s, and a as arguments). As a result, DO is never executed and we finally get

This is similar to the FAILb example from page 916, except that because of the number of arguments the parameter stack overflowed first.

pattern memory The memory available to store hyphenation patterns. This table cannot overflow during normal document processing, since such patterns are loaded only during format generation. If you receive this error during that process, reduce the number of languages for which you load hyphenation patterns into your format. These days pattern loading is normally defined in the file language.dat.

pool size The characters in strings—command names and file names (including the full path on some implementations). If this table overflows, the most likely cause is the use of too many files, especially if they have long absolute path names. This can, for example, happen if a document includes many graphics and one uses graphicspath to make LaTeX search for the images in several directories—every attempt to open a file contributes to this string pool.

save size The set of values to restore when a group ends. With today’s default limits, this is again difficult to overflow. The most likely cause is the use of both local and global assignments to the same object, something that can happen only through the use of low-level TeX programming, since LaTeX assignments are either always local (for most types) or always global (e.g., counter assignments).

To avoid unnecessary growth of the save stack, the document environment has a special implementation¹ so that it does not produce a group (as normal environments do). Without it every new definition would automatically push an unnecessary “undefined” value onto the save stack—unnecessary, because by the time that group would end all processing would stop anyhow.

¹ As a side effect it is impossible to use egin{document} inside another environment since the grouping structure is not obeyed.

semantic nest size The number of token lists being worked on simultaneously. Boxes, math formulas, and other elements start a new list, suspending work on the current structure. Once they are finished TeX has to continue constructing the suspended object, so all such unfinished objects are remembered in the semantic nest stack. With a default size of several hundred objects, it is very difficult to get even close to this limit with normal documents.² In an emergency, TeX offers showlists, which displays all unfinished lists that TeX is currently working on.

² The author could not think of any problematic definition that would not hit any of the other limits first.

text input levels The number of simultaneously open input sources (e.g., files opened by include, input, or usepackage). On the author’s implementation of TeX one would need to nest 1500 files to reach this limit.

In addition to warnings, LaTeX writes informational messages to the transcript file without displaying this information on the terminal. To better distinguish between informational and warning messages, warnings are shown in blue in the following alphabetical listing.

Calculating math sizes for size 〈text size〉

LaTeX has to guess the correct font sizes for subscripts and superscripts because it could not find the information for the current 〈text size〉 in its internal tables. This message usually is followed by several font size correction warnings because LaTeX’s initial guess is seldom successful. This situation can arise when you select an uncommon size using the fontsize command; see Section 7.10.7 if the math formulas look strange.

Checking defaults for 〈cdp〉/〈font shape〉

This message is written in the transcript file at egin{document} while LaTeX is verifying that the substitution defaults for the encoding 〈cdp〉 are sensible. It is followed either by ...okay or by an error message that is generated when the 〈font shape〉 group specified with DeclareFontEncoding is unknown to LaTeX.

Citation '〈key〉' on page 〈number〉 undefined

The 〈key〉 specified as an argument to cite or ocite is not defined by a ibitem command or you need another run of LaTeX (and perhaps BibTeX) to make it known to LaTeX. The latter case is indicated by an additional warning, “Label(s) may have changed...”, as discussed on page 924. The page number is omitted if the warning is emitted by ocite.

Command 〈name〉 invalid in math mode

This is either a warning or an error message indicating that you have used a command in math mode that should be used only in normal text. A warning will be generated when an obsolete, yet still valid, construction is used.

Document Class: 〈name〉 〈date〉 〈additional-info〉

This line is produced by a ProvidesClass command in the document class code. Although not a warning, it appears both on the terminal and in the transcript file. If a document produces different output on different installations, you should compare the “Document Class:”, “File:”, and “Package:” messages to identify any release differences.

Empty 'thebibliography' environment

This warning is issued if a thebibliography environment has no ibitem commands. It often indicates a problem with a BibTeX run. For example, the BibTeX program may have been unable to resolve a single citation.

Encoding 〈name〉 has changed to 〈new name〉 for ...

This warning is issued when in the declaration of a symbol font different encoding schemes in different math versions have been used. It may mean that the DeclareMathSymbol commands for this symbol font are not valid in all math versions.

(end occurred 〈when〉

You receive this warning at the very end of your run whenever TeX finds the end{document} or stop command to be premature. As a warning the message is unfortunately misleading, because it refers to a TeX primitive end that was reused by LaTeX to become the environment end-tag. The 〈when〉 can be one of two cases:

inside a group at level 〈number〉)

In this case the LaTeX run ended while there were still some open groups. Such groups include explicit braces that are not closed (e.g., {itshape..), use of group and egingroup in macro code without their counterparts, and unclosed environments in the source. The latter normally triggers a suitable LaTeX error first (i.e., “egin{〈env〉} on...”) unless you ended the run with stop, since in that case no check for mismatched environments is made.

when 〈condition〉 on line 〈line number〉 was incomplete)

In this case LaTeX completed the run while a low-level TeX conditional remained unfinished. With LaTeX documents using only standard commands, this problem should not occur unless you ended the document inside a file loaded with include. In other cases it probably means there is a bug in a package. Try to identify the source of the conditional (by looking at the 〈line number〉) to see in which command it was used. Note that the 〈line number〉 may not be in the current file—unfortunately, TeX does not divulge the file name. In very difficult situations you can try to use eTeX’s advanced tracing options to pinpoint the problem: if racingifs is set to 1, you will get detailed trace information about nested conditionals as they are executed.

External font 〈name〉 loaded for size 〈size〉

LaTeX has ignored your request to load some font shape at size 〈size〉 and has loaded the external font 〈name〉 instead. (This message is generated by the size function fixed.)

Faking 〈command〉 for font family 〈name〉 in TS1 encoding

The glyph 〈command〉 is not available in the TS1 encoding of the current font family. LaTeX has responded by “faking” it in some way. This is, for example, done for the exteuro glyph (€), if unavailable. Section 7.8.7 describes ways to get a real euro symbol.

File '〈name〉' already exists on the system.
Not generating it from this source

This warning is generated by a filecontents environment when the file 〈name〉 already exists somewhere in the search path of LaTeX. If you want to unpack the file nevertheless, either delete (or rename) the version found by LaTeX or extract the file manually with the help of an editor.

File: 〈name〉 〈date〉 〈additional-info〉

This line is produced from the ProvidesFile command used to identify a file and its last modification date. By convention, the 〈additional-info〉 starts with a version number, though it is not required. Although of the same importance as ProvidesClass, this information is written only to the transcript file to avoid cluttering the terminal with messages. If a document produces different output on different installations, you should compare the “Document Class:”, “File:”, and “Package:” messages to identify any release differences.

File: 〈encoding〉〈family〉 .fd 〈date〉 〈additional-info〉

This important special case of the previous informational message indicates that a font definition file for some 〈encoding〉 (usually displayed in lowercase) and 〈family〉 combination was loaded. Such files contain font shape group declarations and are described in Section 7.10.6.

Float too large for page by 〈value〉

A float is too tall by 〈value〉 to fit in the current extheight. It will be printed on a page by itself (if permitted), thereby possibly overflowing into the bottom margin. If the float is not allowed to go on a float page, it will prevent all further floats in its class from being placed.

Font shape 〈font shape〉 in size 〈size〉 not available

LaTeX issues this message when it tries to select a font for which the requested font attribute combination is not available and a substitution is defined in the internal tables. Depending on the contents of these tables, one of the following additional messages will be issued:

external font 〈name〉 used

LaTeX has selected the external font 〈name〉 in that particular situation and does not know to which font shape group it belongs. (This message is generated by the size function subf.)

size 〈size〉 substituted

LaTeX has selected the correct shape, but since the requested size is not available LaTeX has chosen the nearby size 〈size〉. This action is taken automatically if none of the simple sizes or size ranges in the 〈font shape〉 group declaration matches.

shape 〈font shape〉 tried

LaTeX has selected a different 〈font shape〉 group because the requested one is not available for the requested 〈size〉. (This message is generated by the size function sub.)

Font shape 〈font shape〉 undefined. Using '〈other shape〉' instead

This warning is given when a combination of font attributes is specified for which LaTeX has no font shape definition. For example, requesting fontseries{b} tfamily would normally trigger this warning, since Computer Modern fonts have neither bold typewriter nor bold extended typewriter. However, when the latter combination is requested, you will not receive this warning but only some information in the transcript file because for extbf{ exttt{..}} the .fd files contain an explicit substitution rule.

If LaTeX identifies a particular symbol that it cannot typeset in the requested shape, the above warning is followed by “for symbol 〈name〉”.

Font shape 〈font shape〉 will be scaled to size 〈size〉

LaTeX has loaded the requested font by scaling it to the desired size. To print a document containing scaled fonts, your printer driver must have these fonts in the correct size or must be able to scale them automatically.

Foreign command 〈command〉 ;            
frac or genfrac should be used instead

Although the use of 〈command〉 is not an error, you are strongly discouraged from using this old form for your (generalized) fractions in LaTeX. Use the amsmath commands instead.

Form feed has been converted to Blank Line

The filecontents environment detected a “form feed” character (^^L) in the source and will write it as an empty line (par command if interpreted by LaTeX) into the external file. As filecontents was designed to distribute textual data, it cannot be used for handling arbitrary binary files.

'h' float specifier changed to 'ht'            or
'!h' float specifier changed to '!ht'

You specified h or !h as a float placement without giving any other options. LaTeX requires some alternative in case “here” leads to an impossible placement because not enough room is left on the current page. If you really want to prevent floats from floating, consider using the float package described in Section 6.3.1.

Ignoring text '〈text〉' after end{〈env〉}

This warning is issued by filecontents or filecontents* when textual material is detected following the end tag.

Label '〈key〉' multiply defined

The document contains two or more label commands with the same 〈key〉. References to this 〈key〉 will always refer to the last label defined. Ensure that all 〈key〉s are different.

Label(s) may have changed. Rerun to get cross-references right

LaTeX has detected that the label definitions, as compared to those in the previous run, have been modified and that (at least) one additional LaTeX run is necessary to resolve cross-references properly.

In theory it is possible, though unlikely, that this message will persist regardless of the number of processing runs.¹ If this is the case, compare the .aux files of different runs to determine which label alternates between different states and resolve the problem manually.

¹ For example, if the label is near the page boundary between pages “iii” and “iv”, the use of pageref before the label might result in a situation where the label will be moved to page “iv” if the textual reference “iii” is used, and vice versa.

Loose hbox (badness 〈number〉) 〈somewhere〉

TeX produced a horizontal box with a badness of 13 or greater (which corresponds to using 50% or more of the available stretchability). This warning can be safely ignored unless you are a perfectionist; in fact, it will not be produced unless you change the default for hbadness. See the message “Underfull hbox...” on page 928 for more details.

Loose vbox (badness 〈number〉) 〈somewhere〉

TeX produced a vertical box with a badness of 13 or greater (which corresponds to using 50% or more of the available stretchability). The warning is produced only if vbadness was set to a value below 100. See the message “Underfull vbox...” on page 930 for more details.

Making 〈char〉 an active character

For each character that is turned into a shorthand character, this information message will be written to the transcript file. When a document shows unexpected results, this information might help if the problems are caused by inadvertent use of a shorthand character.

Marginpar on page 〈number〉 moved

A marginpar could not be aligned with the text line to which it was originally attached, because a preceeding marginpar already occupies the space.

Missing character: There is no 〈char〉 in font 〈name〉 !

Watch out for this message in the transcript!

Although this message usually indicates a serious problem, unfortunately it is only written to the transcript file (unless racingonline is positive). It means that somewhere in the source a request for a symbol 〈char〉 was made for which the current font (〈name〉 is the external name) has no glyph in the corresponding position. The displayed 〈char〉 may differ on different TeX installations.¹ For example, using the command symbol can produce this warning because you can ask for any font slot with this command. However, standard font-encoding–specific commands, as discussed in Section 7.11.4 on page 455, should never produce this warning.

¹ Sometimes you see something like ^^G, sometimes real characters are displayed. Unfortunately, there is no guarantee that they correspond to your input: some translation that depends on the operating system may happen when the characters are written to the transcript file.

No author given

You used maketitle without specifying an author first. In contrast to a missing itle this omission generates a warning.

No auxiliary output files

This information is displayed when you use a ofiles declaration in the document preamble.

No characters defined by input encoding change to 〈name〉

The input encoding file 〈name〉.def does not seem to contain any input encoding declarations. For the ascii encoding, this is the expected behavior; for all other encodings, it indicates a problem.

No file 〈name〉

LaTeX displays this information whenever it tries to read from an auxiliary file (e.g., .aux or .toc) but cannot find the file. This is not considered an error since such files are created only after the first run. However, the same routine is also used by include, so that, unfortunately, a missing “include file” will trigger this unsuspicious warning too.

No hyphenation patterns were loaded for the language '〈language〉'

All language definition files check whether hyphenation patterns for the language selected were loaded into the LaTeX format. If this is not the case, this message is displayed and a default set of hyphenation patterns will be used. The default patterns are those loaded into pattern register 0 (typically American English).

No input encoding specified for 〈language〉 language

This message can appear when no specific input encoding was specified in the document and one of the supported languages needs the Cyrillic alphabet for typesetting. For these languages several input encodings are popular; therefore, the language definition insists that the one used must be explicitly mentioned.

No positions in optional float specifier. Default added ...

A float environment (e.g., figure or table) was used with its optional placement argument, but it did not contain any suitable information. Hence, LaTeX used its default placement rules.

Oldstyle digits unavailable for family 〈name〉

You used oldstylenums with a font family that does not contain old-style digits. As an emergency measure LaTeX produced lining digits (from the current font family) instead. See Section 7.5.4 for details.

Optional argument of wocolumn too tall on page 〈number〉

The material in the optional argument to wocolumn was so tall, that fewer than three lines remain on the page. LaTeX will not start two-column mode on the current page and will start a new page instead.

oval, circle, or line size unavailable

The requested size for the mentioned commands is unavailable. LaTeX will choose the closest available size. See, for example, Section 10.4.3 for ways to avoid this problem.

Overfull hbox (〈number〉pt too wide) 〈somewhere〉

TeX was forced to build a horizontal box (e.g., the line of a paragraph or a makebox) of a certain width and was unable to squeeze the material into the given width, even after shrinking any available space as much as possible. As a result, the material will stick out to the right. In most cases this is quite noticeable, even if the total amount is small. You have to correct this problem manually, since TeX was unable to resolve it (Sections 3.1.11 and B.3.3 give some advice). For a list and explanation of the possible origins (i.e., the 〈somewhere〉), see the warning “Underfull hbox...” on page 928.

Overfull vbox (〈number〉pt too wide)) 〈somewhere〉

TeX was asked to build a vertical box of a fixed size (e.g., a parbox or a minipage with a second optional argument; see Appendix A.2.2 on page 866) and found more material than it could squeeze in. The excess material will stick out at the bottom. Whether this result poses a problem depends on the circumstances. For a list and explanation of the possible origins (i.e., the 〈somewhere〉), see the warning “Underfull vbox...” on page 930.

Overwriting encoding scheme 〈something〉 defaults

This warning is issued by DeclareFontEncodingDefaults when it overwrites previously declared defaults for “text” or “math”.

Overwriting 〈something〉 in version 〈name〉 ...

A declaration, such as SetSymbolFont or DeclareMathAlphabet, changed the assignment of font shapes to 〈something〉 (a symbol font or a math alphabet) in math version 〈name〉.

Package: 〈name〉 〈date〉 〈additional-info〉

This line is produced by the ProvidesPackage command, which is used to identify a package and its last modification date. By convention, the 〈additional-info〉 starts with a version number, though it is not required. Although of the same importance as ProvidesClass, this information is written to just the transcript file to avoid cluttering the terminal with messages. If a document produces different output on different installations, you should compare the “Document Class:”, “File:”, and “Package:” messages to identify any release differences.

Redeclaring font encoding 〈name〉

This warning is issued if DeclareFontEncoding is used for an encoding that is already defined (thereby potentially changing its defaults).

Redeclaring math accent 〈name〉

This warning is issued if DeclareMathAccent is used for a math accent that was previously declared. If the command to be declared is known but not an accent, you get an error message instead.

Redeclaring math alphabet 〈name〉

A DeclareMathAlphabet or DeclareSymbolFontAlphabet command was issued to declare 〈name〉, which was already defined to be a math alphabet identifier. The new declaration overrides all previous settings for 〈name〉.

Redeclaring math symbol 〈name〉

The command 〈name〉 was already declared as a math symbol and your declaration overrides the old definition.

Redeclaring math version 〈name〉

You issued a DeclareMathVersion command for a version that was already declared. The new declaration overrides all previous settings for this version with the default values.

Redeclaring symbol font 〈name〉

You issued a DeclareSymbolFont command for a symbol font that was previously declared. The new declaration overrides the symbol font in all known math versions.

Reference '〈key〉' on page 〈number〉 undefined

A reference created with ef, pageref, or one of the other cross-reference commands discussed in Chapter 2 used a 〈key〉 for which LaTeX has not seen a corresponding label command. If the label is somewhere in the document, you simply need another LaTeX run to make it known to LaTeX. This situation is indicated by the additional warning “Label(s) may have changed...” discussed on page 924.

Size substitutions with differences up to 〈size〉 have occurred

This message will appear at the end of the run if LaTeX selected at least one significantly different font size because a requested size was not available. The 〈size〉 is the maximum deviation that was needed.

Some font shapes were not available, defaults substituted

This message will appear at the end of the run if LaTeX had to use automatic font substitution for some font shapes.

Tab has been converted to Blank Space

The filecontents environment detected a “tab” character (^^I) in the source and will write it as a space into the external file.

Text page 〈number〉 contains only floats

One or more floats processed as “top” or “bottom” floats are together so tall that very little space (less than two lines) is left for normal text on the current page. Therefore, LaTeX decided to place only floats on the page in question (even if some or all of the floats do not explicitly allow for this placement). This message can appear only when the placement parameters for floats were changed drastically from their default values; see the beginning of Chapter 6 for details.

There were multiply-defined labels

This warning appears at the end of a LaTeX run when LaTeX detected at least one pair of label or ibitem commands with the same key. Check the transcript file and make sure that all keys used are different.

There were undefined references

This warning appears at the end of a LaTeX run when LaTeX detected references to unknown keys and concluded that rerunning the document would not resolve them. You should check the transcript file for all occurrences of “Reference 〈key〉 undefined” and “Citation 〈key〉 undefined” and correct them, either by fixing a misprint or by adding the necessary label or ibitem commands. In case of missing citation 〈keys〉, all you may have to do is rerun BibTeX and then LaTeX.

Tight hbox (badness 〈number〉) 〈somewhere〉

TeX produced a horizontal box and had to shrink the interior spaces. You will see this message only if hbadness is set to a value less than 100. See the message “Underfull hbox...” below for more details.

Tight vbox (badness 〈number〉) 〈somewhere〉

TeX produced a vertical box and had to shrink the interior spaces. You will see this message only if vbadness is set to a value less than 100. See the message “Underfull vbox...” on page 930 for more details.

Try loading font information for 〈cdp〉+〈family〉

You will find such a message in the transcript file whenever LaTeX tries to load a .fd file for the encoding/family combination 〈cdp〉/〈family〉.

Unable to redefine math accent 〈accent〉

This warning is rare but it may be issued when loading the amsmath package with nonstandard mathematical fonts.

Underfull hbox (badness 〈number〉) 〈somewhere〉

TeX was forced to build a horizontal box (e.g., the line of a paragraph or a makebox) of a certain width, and the white space within that box had to stretch more than it was designed to do (i.e., stretched more than 100% of the available plus parts in stretchable spaces). Internally, this situation is expressed by a badness value greater than 100; a value of 800 means that twice the total stretchability was used to produce the required width.¹

¹ The exact formula is min(100r³, 10000) where r is the ratio of “stretch used” to “stretch available”, unless there is infinite stretch present (e.g., introduced by a command like hfill), in which case the badness will be zero.

Whether such an underfull box actually presents a noticeable problem is something that you may have to check visually in the produced output. If the badness is 10000 the box can be arbitrarily bad. Since TeX’s value for infinity is quite low, it might mean that TeX has favored one very bad line over several bad but still acceptable lines that appear in succession. In that case using emergencystretch can help you; see Section 3.1.11.

The limit of badness values above which such warnings are shown is controlled by the integer parameter hbadness. LaTeX’s default is 1000, so warnings appear only for really bad boxes. If you want to produce an important document try a more challenging value, such as hbadness=10, to find out how many lines TeX really considers imperfect.

Note that the warning always talks about hbox, regardless of the actual box construct used in the source, since it is directly generated by TeX. The location where the problem occurred is indicated by 〈somewhere〉, which is one of the following four possibilities:

detected at line 〈line number〉

An explicitly constructed box (construction ending at line 〈line number〉 in the source) has the problem—for example, a makebox with an explicit width argument or some other LaTeX construct that builds boxes.

has occurred while output is active

TeX was in the process of building a page and encountered the problem while attaching running headers and footers and the like. Since this is an asynchronous operation, no line number is given. Look at the page generated closest to where the warning was issued to determine whether it warrants manual correction.

in alignment at lines 〈line numbers〉

The box is part of a tabular or some math alignment environment. The 〈line numbers〉 give you the source position of the whole alignment structure, since by the time TeX encounters the problem it no longer has a way to relate it back to the source in more detail.

in paragraph at lines 〈line numbers〉

The underfull box is due to a badly spaced line in the paragraph (source line numbers given as 〈line numbers〉). The additional symbolic display of the line in question should help you to pinpoint the problem.

Underfull vbox (badness 〈number〉) 〈somewhere〉

TeX was forced to build a vertical box (e.g., a parbox or a minipage) of a certain height, and the vertical space in that box had to stretch more than it was supposed to; see the discussion of badness and stretchability in the description of the “Underfull hbox...” warning. You can suppress all warnings for badness values below a certain limit by setting vbadness=〈value〉. Then LaTeX issues warnings only for boxes with a badness larger than 〈value〉 (the default is 1000). The 〈somewhere〉 indicates the origin of the problem and can be one of the following cases:

detected at line 〈line number〉

The box was explicitly constructed (the 〈line number〉 points to the end of the box construction) and there is not enough stretchable space available. For example,

would produce this warning because the box should be 2 inches high and the contents should fill this height (argument [s]), but there is nothing stretchable available. For instance, something like parvfill between the two words. See Appendix A.2.2 for details on paragraph boxes.

has occurred while output is active

In the most frequent case, the space on the current page needed stretching beyond acceptable limits in TeX’s eyes. Whether this is visually a real problem depends on many factors, such as the type of spaces on the page. For example, a large stretch in front of a heading is usually less severe than a spaced-out list. Thus, the best advice is to check such pages manually. Often, enlargethispage or pagebreak will help.

If the problem appears surprisingly often, then the spacing parameters for lists, paragraphs, and headings should be examined to see whether they are too rigid (see Chapters 2 to 4). Also check whether the extheight corresponds to an integral number of text lines; see the discussion on page 197.

in alignment at lines 〈line-numbers〉

This warning should not arise with standard LaTeX but can occur in some specialized applications. In such a case use 〈line-numbers〉 to identify the source lines in your document.

Unused global option(s): [〈option-list〉]

Some of the options specified on documentclass have been used by neither the class nor any package in the preamble. A likely reason is that the names of the options have been misspelled. Also note that some packages do not react to global options, but only to those explicitly specified when loading the package. See Appendix A.4 for details.

Writing file '〈name〉'

This informational message is produced by both filecontents and filecontents* when they write their body to an external file 〈name〉.

Writing text '〈text〉' before end{〈env〉} as last line of 〈file〉

This warning is issued by the filecontents or filecontents* environment when it detects textual material directly preceeding the end tag.

You have more than once selected the attribute '〈attrib〉' for language 〈language〉

This message is displayed if the same attribute is entered more than once in the second argument of languageattribute; only the first occurrence will trigger the activation of the attribute.

You have requested 〈package-or-class〉 '〈name〉', but the 〈package-or-class〉 provides '〈alternate-name〉'

You requested loading of 〈name〉 via usepackage or RequirePackage (in case of a package) or via documentclass or LoadClass (in case of a class), but the package or class provides a variant of the original with the internal name 〈alternate-name〉. Unless this was a typo by the package or class provider, it means that your installation has a package or class variant that is likely to behave differently from the original. Thus, your document may be formatted differently when processed on another installation. Whether this is the correct behavior is something you need to investigate by looking at the package or class in question.

Specifying a relative or absolute path name triggers this warning as a side effect.

You have requested release '〈date〉' of LaTeX, but only release '〈old-date〉' is available

A NeedsTeXFormat command has requested a LaTeX release of at least 〈date〉 but the date of your format is 〈old-date〉. Usually, such a request is made to ensure that a certain feature of the LaTeX format is available, so it is likely that your document will produce additional errors or strange formatting later. Update to a more recent version of LaTeX.

You have requested, on line 〈num〉, version '〈date〉' of 〈name〉, but only version '〈old-date〉' is available

A class or package was required to have a date not older than 〈date〉 but the version on your installation is from the date 〈old-date〉. Update the class or package in question.

Displaying command definitions

For this purpose TeX offers the command show, which displays the definition of the token following it and then stops and displays a question mark while waiting for user intervention. For example, after defining xvec as in Example A-1-4 on page 844, we can display its definition as follows:

This will produce the following output on the terminal and in the transcript file:

The first line, which starts with >, shows the token being displayed (xvec) and gives its type (long macro), indicating that xvec is a macro that accepts par commands in its argument; in other words, this macro was defined with ewcommand rather than ewcommand*. The second line shows the argument structure for the command (up to ->), revealing that the command has one argument (#1). Note that while the argument on the ewcommand declaration was indicated with [1], it is now shown differently. The rest of the line—and possibly further lines, if necessary—shows the definition part. The code is terminated with a period that is not part of the definition but helps to identify stray spaces at the end of the definition, if any. Note that the code display is normalized. Thus, after a command that would swallow subsequent spaces, you will see a space regardless of whether a space was coded in the original definition.

Following the display of the definition, the source line (including the line number in the input file) is shown. Then LaTeX stops with a question mark. To continue you can press enter. Alternatively, you can type h to see what other possibilities are available.

Not all commands produce such easily understandable output. Assume that you try to display a command that was defined to have an optional argument, such as lvec as defined in Example A-1-5 on page 845:

In that case you will get this result:

Apparently, the lvec command has no arguments whatsoever (they are picked up later in the processing). And something else is strange in this output: what is \lvec? Is it the command \ followed by the letters lvec, or is it a strange command \lvec that has two backslashes as part of its name? It is actually the latter, though there is no way to determine this fact from looking at the output of the show command. Such strange command names, which cannot be generated easily by the user, are sometimes used by LaTeX internally to produce new command names from existing ones using csname and endcsname and other low-level mechanisms of TeX.

Displaying internal commands with strange names

So what should you do, if you want to see the definition of \lvec? It should be clear that writing show in front of such a command will not work, as in normal situations TeX will see \ and think that it is the command to “show”. For that reason, you have to use the same low-level mechanisms first to generate the command name in a way that it is considered a single token by TeX and then to feed this token to show:

Technically, what happens is that a command name is generated from the tokens between csname and endcsname. Inside that construct, the string command turns the command lvec into a sequence of characters starting with a backslash that no longer denotes the start of a command. This is why the resulting command name contains two backslashes at the beginning. The expandafter command delays the evaluation of the following show command so that csname can perform all of its work before show is allowed to look at the result.

That’s quite a mouthful of low-level TeX, but after typing it in, we are rewarded with the following output:

This time we do not see a source file line after the command display, but the words <recently read>. They indicate that TeX has assembled the token \lvec somewhere in memory rather than reading it directly from a file.

What would happen if we forgot the initial expandafter in the previous input? We would get the following result:

Detecting a primitive command

First we are told that csname is a csname, which seems like totally useless information but, in fact, indicates that csname is a primitive command or register already built into the TeX program—in contrast to, say, lvec, which was a macro defined via ewcommand. LaTeX also shows how far it has read the input line by placing the unread tokens (string and friends) into the next line. Since we carry on, TeX will stop again shortly (after having consumed the whole line) to complain about a spurious endcsname because the matching csname was shown but not executed.

Displaying register values

The show command is useful for learning about commands and their definitions or finding out if something is a primitive of TeX. But it does not help in finding the current values of length or counter registers. For example,

will give us the following information:

From the above we can deduce that parskip is a TeX primitive (the fact that it is a rubber length is not revealed), that opmargin is actually the dimen register (rigid length) with register number 73, and that opsep is the skip register (rubber length) with number 23.

If we want to know the value of any such register, we need to deploy a different TeX primitive, called showthe instead of show, which gives us the following output on the terminal and also proves that parskip is, indeed, a rubber length:

Using showthe in this way allows us to display the values of the length registers allocated with ewlength and of internal TeX registers such as aselineskip and olerance. What we cannot display directly with it are the values of LaTeX counters allocated with ewcounter. For this we have to additionally deploy a value command that turns a LaTeX counter name into a form that is accepted by showthe. For example,

would show the current value of the footnote counter on the terminal.

Typesetting command definitions or register values

Instead of displaying the meaning of a macro or the value of a register on the terminal, you can alternatively typeset this kind of data by using meaning instead of show and he instead of showthe. The output is slightly different: the name of the token is not shown by meaning; instead, only its type and “meaning” is presented. Compare the next example with the output shown earlier in this section.

If displaying command definitions or register values is insufficient for determining a problem, you can alternatively trace the behavior of the commands in action; see Section B.3.5 on page 945.

Every page output will start with the string Completed box being shipped out followed by the current page number in brackets. Then you get many lines showing the boxes that make up the page, starting with a vbox (vertical box) and its sizes in pt containing the whole page. To indicate that something is the contents of a box, everything inside is recursively indented using periods instead of blanks. Spaces, even if they are rigid, are indicated by the keyword glue (see line 3 or 6); stretchable space has some plus and/or minus components in its value, as we will see later. Whether it is a horizontal or a vertical space is determined by the box in which this space is placed. For example, the glue of 16.0pt on line 3 is a vertical space that came from opmargin; see also Example B-3-1. In the extract you also see an empty vbox of height 12pt (lines 5 to 7), which is the empty running header, followed in line 8 by the space from headsep (25pt), followed by the box containing the text area of the page starting at line 10. Lines 15 and following show how individual characters are displayed; here T1/cmr/m/n/10 indicates the font for each character. The glue in between (e.g., line 19), marks an interword space with its stretch and shrink components.

As a second example from a page trace, we show the symbolic display of the structures near a line break. You see the space added by TeX at the right end of a text line ( ightskip on line 5) and the box containing the line. Thus, line 6 is outdented again. It contains a symbolic representation for the costs to TeX to break after this line, indicated by the command penalty. The actual value here is due to the value of the clubpenalty parameter.¹ This is followed in line 7 by the vertical space added between the lines, computed by TeX by taking the value of aselineskip and subtracting the depth of the previous line box and the height of the following line box, which starts at line 8.

¹ The penalty to break after the first line in a paragraph is given by the integer parameter clubpenalty; the cost for breaking before the last line by widowpenalty. Both default to 150, that is, they slightly discourage a break.

As a final example, we look at some part of the symbolic page output produced from a line like this:

The particular part of interest is the one generated from end{itemize} and section{Test}. What we see here (lines 1 to 7) is a curious collection of glue statements, most of which cancel each other, intermixed with a number of penalty points:

These lines are generated from various addpenalty and addvspace commands issued; for example, lines 1 and 2 are the penalty and the rubber space added by end{itemize}. The section command then adds a breakpoint to indicate that the place before the section is a good place to break a page (using @secpenalty with a value of -300). In fact, the break should be taken before the glue from line 2, or else there would be a strange space at the bottom of that page. As it is technically impossible to remove material from the vertical galley, addpenalty uses the trick to back up by adding a negative space (line 3), add the penalty (line 4), and then reissue the glue (line 5). In lines 6 and 7, the same method is used by addvspace to add the vertical space before the heading.

Lines 8 and 9 are added by TeX when placing the actual heading text (line 10) into the galley. Note that technically the heading is considered a “paragraph”, so parskip is added. This is the reason why enlarging this parameter requires careful planning. The same care should be taken when adjusting other parameters (like the one added on line 7).

Side effect of showoutput

The showoutput command will also produce symbolic displays of overfull boxes. Tracing ends at the next closing brace or environment. Thus, to see the output for full pages, you have to ensure that the page break happens before the next group ends.

Setting racingonline to a positive value will ensure that the tracing information will appear not only in the transcript file (default), but also on the terminal.

Processing the previous paragraph starting with “If you want to...” as a separate document, we get the following lines of tracing information:

The first line starting with two percent signs shows the target height for the page (i.e., 522pt in this case), which means 43 lines at a aselineskip of 12pt with 2pt missing since the skip to position the first base line, opskip, has a value of 10pt. If the goal height does not result in an integral number of lines, problems like underfull vboxes are likely to happen.

Target size of a break

The remaining lines, starting with one percent sign, indicate a new potential page-break position that TeX has considered. You can interpret such lines as follows: t= shows the length of the galley so far and, if the galley contains vertical rubber spaces, their total amount of stretch and shrink. Line 4, for example, shows that in the layout of this book verbatim displays have an extra space of 10pt plus a stretch of 4pt (the verbatim lines are typeset in a smaller font with only 11pt of aselineskip) and the same amount is added between lines 4 and 5.

Page goal height

The g= specifies the goal height at this point. This value changes only if objects like floats have reduced the available space for the galley in the meantime.

Page badness

With b=, TeX indicates the badness of the page if a break would be taken at this point. The badness is calculated from the factor by which the available stretch or shrink in t= must be multiplied to reach the goal height given in g=. In the example the page is barely filled, so it is always 10000 (infinitely bad), except for line 7, where, due to the added fil stretch, the page is suddenly considered optimal (b=0).

Break penalty

With each breakpoint TeX associates a numerical penalty as the cost to break at this point. Its value is given by p=. For example, it is not allowed to break directly before the verbatim display, which is why there is a large increase in t= between lines 3 and 4. On the other hand, a break after the display is given a bonus (p=-51). Line 5 shows that breaking after the first line of the two-line paragraph fragment following the verbatim text is considered bad (p=300), as it would result in both a club and a widow line (clubpenalty and widowpenalty each have a value of 150 and their values are added together).

Costs of a page break

Finally, c= describes the calculated cost to break at this breakpoint, which is derived from a formula taking the badness of the resulting page (b=) and the penalty to break here (p=) into account. TeX looks at these cost values and will eventually break at the point with minimal cost. If the line ends in #, then TeX thinks that it would be the best place to break the page after evaluating all breakpoints seen so far. In the example, all lines show this #—not surprising, given that TeX considers all but the last breakpoint to be equally bad.

If the pages would become too full if a break is taken at a particular breakpoint, then TeX indicates this fact with b=*. At this point TeX stops looking for other breakpoints and instead breaks the page at the best breakpoint seen so far.

For additional details on the output produced by these low-level display devices, consult [82, p.112].

showing you a symbolic display of the text line and the line number(s) of the paragraph containing it. If you look at the symbolic display, you can easily diagnose that the problem is TeX’s inability¹ to hyphenate the word “paragraph”. To explicitly flag such lines in your document, you can set the parameter overfullrule to a positive value. For the present paragraph it was set to 5pt, producing the blob of ink clearly marking the line that is overfull. The standard document classes enable this behavior with the option draft. On the other hand, you may not mind lines being only slightly overfull. In that case you can change the parameter hfuzz (default 0.1pt); only lines protruding by more than the value of hfuzz into the margin will then be reported.

¹ TeX is, in fact, perfectly capable of hyphenating para-graph; for the example, we explicitly prevented it from doing so. The paragraph would have been perfect otherwise.

If TeX is unable to break a paragraph in a satisfying manner, the reasons are often hyphenation problems (unbreakable words, as in the above example), problems with the parameter settings for the paragraph algorithm, or simply failure of the text to fit the boundary conditions posed by the column measure or other parameters, together with aesthetic requirements like the allowed looseness of individual lines. In the latter case the only remedy is usually a partial rewrite.

Running this statement through LaTeX will give you some tracing output on the terminal and in the transcript file. The hyphenation points determined by TeX are indicated by a hyphen character:

If you want to add the missing hyphenation points, you can specify all hyphenation points for one word locally in the text using -, for example,

Alternatively, you can use a hyphenation declaration in the preamble:

The latter technique is particularly useful when you detect a wrong hyphenation, or often use a word for which you know that TeX misses important hyphenation points. Note that such explicit specifications tell TeX how to hyphenate words that are exactly in the form given. Thus, the plural “laryngologists” would be unaffected unless you specify its hyphenation points as well.

The hyphenation declarations apply to the current language, so if a document uses several languages—for example, by using the methods provided by the babel system—then you need to switch to the right language before issuing the relevant declarations.

¹ These parameters are also turned on by a racingall command, so you may get many lines of paragraph tracing data, even if you are interested in something completely different.

For readers who really want to understand the reasons behind certain decisions, we show some example data with detailed explanations below.

Paragraph tracing will produce output that looks somewhat scary. For instance, one of the previous paragraphs generated data that starts like this:

Up to three passes over paragraph data

Line 2 says that TeX has immediately given up trying to typeset the paragraph without attempting hyphenation. This is due to the value of pretolerance being set to 100 in the sources for the book; otherwise, TeX may have gotten further or even succeeded (in English text quite a large proportion of paragraphs can be reasonably set without hyphenating¹). In addition to @secondpass, you sometimes see @emergencypass, which means that even with hyphenation it was impossible to find a feasible solution and another pass using emergencystretch was tried.² Line 3 shows how far TeX had to read to find that first potential line ending that results in a badness of less than ∞ = 10000. Line 4 gives details about this possible break. Such lines start with a single @; the via gives the previous breakpoint (in this case @@0, which refers to the paragraph start), the line badness (b=), the penalty to break at this point (p=), and the so-called demerits (d=) associated with taking that break (a “cost” that takes into account badness, penalty, plus context information like breaking at a hyphen or the visual compatibility with the previous line).

¹ For the LaTeX Companion with its many long command names this is less likely.

² For this to happen emergencystretch needs to have a positive value. See also the discussion in Section 3.1.11.

In line 5, TeX informs us that it would be possible to form a very loose first line ending in the breakpoint given by line 3 with a total cost (t=) equal to the demerits shown on line 4. This line would be formed by starting at breakpoint @@0. The notation line 1.0 gives the line number being made and the suffixes .0,.1,.2,.3, respectively, stand for very loose, loose, decent, and tight interword spacing in the line. This classification is important when comparing the visual compatibility of consecutive lines.

TeX now finds more and more potential line breaks, such as after “if” in line 6, and after “a” in line 9. Each time TeX tells us what kind of lines can be formed that end in the given breakpoint. If b=* appears anywhere in the trace data, it means that TeX could not find a feasible breakpoint to form a line and had to choose an infeasible solution (i.e., one exceeding olerance for the particular line).

By hyphenating the word doc-u-ment it finds two more breakpoints (lines 12 and 15). This time you see a penalty of 50—the value of the parameter hyphenpenalty (breaking after a hyphen)—being attached to these breaks. Line 15 is the last breakpoint that can be used to produce the first line of the paragraph. All other breakpoints would produce an overfull line. Hence, the next tracing line again shows more text; none of the potential breakpoints therein can be used as they would form a second line that exceeds olerance.

Here the breakpoint can be used to form a second line in two different ways: by starting from breakpoint @@1 (line 19) or by starting from breakpoint @@2 (line 20). If we compare just these two solutions to form the second line of the paragraph, then the first would be superior: it has a badness of 1194, whereas the second solution has a badness of 2875, which results in a factor of 5 in “costs” (d=). Nevertheless, TeX considers the second break a better solution, because a first line ending in @@1 is so much inferior to a line ending in @@2 that the total cost for breaking is less if the second alternative is used. TeX therefore records in line 21 that the best way to reach the breakpoint denoted by line 18 is by coming via @@2 and results in a total cost of t=9539134. For the rest of the processing, TeX will not need to know that there were several ways to reach @@6; it just needs to record the best way to reach it.

More precisely, TeX needs to record the best way to reach a breakpoint for any of the four types of lines (very loose, loose, decent, tight), since the algorithm attaches different demerits to a solution if adjacent lines are visually incompatible (e.g., a loose line following a tight one). Thus, later in the tracing (lines 22–40 are not shown), we get the following output:

This output indicates that there are three ways to form a line ending in “by”: by starting from @@3, @@4, or @@5. A line with a badness of 12 or less is considered decent (suffix.2); a line stretching, but with a badness not higher than 100, is considered loose (suffix.1). So here TeX records two feasible breakpoints for further consideration—one going through @@5 and one going through @@4.

Which path through the breakpoints is finally selected will be decided only when the very end of the paragraph is reached. Thus, any modification anywhere in the paragraph, however minor, might make TeX decide that a different set of breakpoints will form the best solution to the current line-breaking problem, because it will produce the lowest total cost. Due to the complexity of the algorithm, minor modifications sometimes have surprising results. For example, the deletion of a word may make the paragraph a line longer. This may happen because TeX decides that using uniformly loose lines, or avoiding hyphenation of a word, is preferable to some other way to break the paragraph. Further details, describing all parameters that influence the line-breaking decisions, can be found in [82, p.98]. If necessary, you can force breakpoints in certain places with linebreak, or prevent them with olinebreak or by using ~ in place of a space. Clearly, choices in the early parts of a paragraph are rather limited and you may have to rewrite a sentence to avoid a bad break. But later in a paragraph nearly every potential break will become feasible, being reachable without exceeding the specified olerance.

Setting the value of looseness is not guaranteed to have any effect. Shortening a paragraph is more difficult for TeX than lengthening it, since interword spaces have a limited shrinkability that is small in comparison to their normal stretchability. The best results are obtained with long paragraphs having a short last line. Consequently, extending a paragraph works best on long paragraphs with a last line that is already nearly full, though you may have to put the last words of the paragraph together in an mbox to ensure that more than one word is placed into the last line.

On-line tracing

We already encountered racingonline. If it is set to a positive value all tracing information is shown on the terminal; otherwise, most of it is written only to the transcript file. This parameter is automatically turned on by racingall.

With racingoutput, tracing of page contents is turned on. What is shown depends on two additional parameters: showboxdepth (up to which level nested boxes are displayed) and showboxbreadth (the amount of material shown for each level). Anything exceeding these values is abbreviated using etc. or [] (indicating a nested box) in the symbolic display. The LaTeX command showoutput sets these parameters to their maximum values and racingoutput to 1, so that you get the most detailed information possible. The showoutput command is automatically called by racingall.

The contents of boxes

To see the contents of a box produced with sbox or savebox, you can use the TeX command showbox:

However, the result is fairly useless if you do not adjust both showboxdepth and showboxbreadth at the same time. Hence, a better strategy is to use LaTeX’s showoutput:

Notice the use of braces to limit the scope of showoutput. Without the braces you would see all of the following page boxes, which might not be of much interest. The same type of symbolic display as discussed in Section B.3.2 will be displayed on the terminal:

If you add scrollmode or atchmode before the showbox command, LaTeX will not stop at this point. You can then study the trace in the transcript.

Local restores

To see what values and definitions TeX restores when a group ends, you can set racingrestores to a positive value. It is automatically turned on by racingall.

TeX’s stack of lists

With showlists you can direct TeX to display the stack of lists (vertical, horizontal) that it is currently working on. For instance, putting showlists into the footnote¹ of the present paragraph, we obtain the following output in the transcript file:

¹ A footnote starts a new vertical list and, inside it, a new horizontal list for the footnote text.

Here the text of the footnote started at line 3066 and the spacefactor was set to 1000 at its beginning. The footnote itself was started on that same line, contributing the “internal vertical mode”, and TeX correctly disregarded the outer value of prevdepth. The footnote was part of a paragraph that started on source line 3060, which in turn was embedded in a vertical list that started on line 0, indicating that it is the main vertical galley. Finally, the output shows some information about the current page list that is being built, including its current height, its target height, and the value of prevdepth (i.e., the depth of the last line on the page at the moment).

Because of the default settings for showboxbreadth and showboxdepth, the contents of all lists are abbreviated to []. To get more detail adjust them as necessary or use showoutputshowlists to get the full details.

Tracing the processing

Not very useful on its own, but helpful together with other tracing options, is racingcommands, which shows all primitives used by TeX during processing. A related internal integer command is racingmacros, which shows all macro expansions carried out by TeX. If set to 2, it will also display the expansion of conditionals. Both parameters are automatically turned on by racingall.

Tracing lost characters

When everything is set up correctly, it is unlikely that TeX will ever access a font position in the current font that is not associated with a glyph. However, some commands, such as symbol, can explicitly request any font slot, so it is not impossible. Unfortunately, TeX does not consider this event to be an error (which it should). It merely traces such missing characters by writing unsuspicious transcript entries, and it takes that step only if racinglostchars is set to a positive value. LaTeX tries to be helpful by initializing this internal integer to 1.

Stepping through a document

Finally, you can direct TeX to step through your files line by line. When setting pausing to 1, each source line is first displayed (suffixed with =>). TeX then waits for instructions regarding what to do with it. Pressing 〈Enter〉 instructs TeX to use the line unchanged; anything else means that TeX should use the characters entered by the user instead of the current line. TeX then executes and typesets whatever it was passed, displays the next line, and stops again. To continue normal processing you can reply with pausing=0, but remember that this is used in place of the current source line, so you may have to repeat the material from the current source line as well.

1. There is no corresponding command to turn off tracing. As a consequence, you have to delimit the scope, which is not always convenient or even possible.

2. Some parts of LaTeX produce enormous amounts of tracing data that is of little or no interest for the problem at hand.

For example, if LaTeX has to load a new font, it enters some internal routines of NFSS that scan font definition tables and perform other activities. And 99.9% of the time you are not at all interested in that part of the processing, but just in the two lines before and the five lines after it. Nevertheless, you have to scan through a few hundred lines of output and try to locate the lines you need (if you can find them).

Another example is a statement such as setlengthlinewidth{1cm}. With standard LaTeX this gives 5 lines of tracing output. With the calc package loaded, however, it will result in about 60 lines of tracing data—probably not what you expected and not really helpful unless you try to debug the calc parsing routines (which ideally should not need debugging).

More tracing info available with eTeX

To solve the first problem, the trace package [122] by Frank Mittelbach defines a pair of commands, raceon and raceoff. If LaTeX is used on top of a TeX engine, then raceon is essentially another name for racingall: it turns on the same tracing switches (albeit in a different order to avoid tracing itself). If LaTeX is run on top of the eTeX engine, then the tracing of assignments and groups is also turned on.¹

¹ The corresponding eTeX switches are racingassigns and racinggroups; see [27].

Another difference between raceon and racingall is that the latter will always display the tracing information on the terminal, whereas raceon can be directed to write only to the transcript file if you specify the option logonly. This is useful when writing to the terminal is very slow (e.g., if running in a shell buffer inside emacs).

To solve the second problem, the trace package has a number of internal commands for temporarily disabling tracing. It redefines the most verbose internal LaTeX functions so that tracing is turned off while they are executing. For example, the function to load new fonts is handled in this way. If a document starts with the two formulas

then LaTeX will load 22 new fonts² at this point. Using standard racingall on that line will result in roughly 7500 lines of terminal output. On the other hand, if raceon is used, only 350 lines will be produced (mainly from tracing small).

² You can verify this with the loading option of the tracefnt package.

The commands for which tracing is turned off are few and are unlikely to relate to the problem at hand. However, if you need full tracing, you can either use racingall or specify the full option. In the latter case, raceon traces everything, but you can still direct its output exclusively to the transcript file.