Aller au contenu

Introduction

Sometimes Overleaf will report errors which arise from files with names such as output.toc, output.bbl, etc., but those files don’t even exist in your project. So where do such files come from and, more importantly, how do you locate and fix the errors?

Gen-toc-error.png
“But I don’t even have this output.toc file in my project!”

These “mysterious files” are artifacts: ancillary files generated during the LaTeX compilation process, but they can also trigger errors which usually originate from coding issues within your project’s source files. This help article uses a real error-ridden example to show how to track down such errors to their point-of-origin within your project source file(s).

Files generated during the LaTeX compilation process

Apart from the output .pdf file, the LaTeX compilation process generates several file types which contain information about labels, cross-references, page numbers etc. Some ancillary file-types are not directly created by the LaTeX compiler, but by other processing tools used during typesetting: for example, formatted reference lists and indices. These generated files must be read by the compiler on subsequent runs, so that the final .pdf file is populated with the correct lists, citations and cross-references.

The need for LaTeX, and associated processing tools, to write and read ancillary data files means that several compilation/processing steps may be required before the total file-data-set converges (stabilizes) to produce the final typeset (stable) .pdf file. A typical typesetting cycle might be:

pdflatex\(\mapsto\)bibtex\(\mapsto\)pdflatex\(\mapsto\)pdflatex

On a local LaTeX installation you may need to execute each intermediate step yourself, or you might use a build tool such as make, latexmk or arara, to automate this chain of processes. Overleaf uses latexmk, and this video shows what happens every time you click the “Recompile” button in your Overleaf project.

Usually, generated files have the same filename as the .tex file being compiled; for example, if you are compiling main.tex, the generated files would be named main.aux, main.toc, main.lof etc. However, on Overleaf the compile \jobname is always set to output, so the generated files from your Overleaf project are always named output.aux, output.toc, output.lof etc. These generated files can be downloaded from your Overleaf project, but they can’t be viewed or edited on Overleaf.

Compile errors reported from generated files

Coding errors in the main project .tex file may be carried through to the generated files. For example, an unescaped & in \section{Introduction & Background} would make its way into the generated .toc file. When the generated .toc file is subsequently read-in by the next pdflatex compile run, an error message is then raised as “coming from the .toc file”. However, current LaTeX logs and error-reporting do not make any connection from lines in the .toc file (and other generated files) to their originating location in the source .tex file: it may not be immediately obvious where the original error should be corrected.

Here’s an example of how errors are presented in another LaTeX editor: whilst you can click on the error message to open the related line in the generated .toc or .aux file, there isn’t a path to go from the error to the originating location in the .tex file. And even if you correct the error by replacing & with \& in the .toc file, that doesn’t really solve the problem: the next time you compile the .tex file, the .toc file is regenerated and same error will be re-written to the .toc file.

Texstudio-errors-generated-files.gif

When an error is reported as coming from generated files, the correct way to solve them is to locate the actual originating error in the source files, and correct those. The error messages usually include contextual information, some text or code surrounding the error, so doing a text search in the source files will help to locate them. The errors themselves are often common: you may look up some common errors on this help page, or in the TeX FAQ list.

First, try clearing the generated files

Sometimes, errors in the generated files are left-overs from a previous compile. Even if you had corrected the errors in your .tex file and recompile, the generated files, still containing the errors, might still be read by the compiler, producing the same errors as before. You can try deleting the generated files before you recompile. Instructions on how to do this on Overleaf can be found here.

If you’re still seeing the same errors even after deleting all generated files and recompiling, it’s likely that there are genuine errors in your source files.

Playing detective: locating errors in generated files

The following sections offer some tips on where to look for such errors. We’ll use the following purposely error-ridden example project for our sleuthing practice. Ready? Let’s go!

 Open an error-ridden Overleaf project! The project should look something like this 😲:

Image showing LaTeX project errors

Errors from .aux files

The .aux file contains information about use of \label{...} declarations and \cite{...} in the .tex file, so these are useful things to check.

Let’s look at this first error from our example error-ridden project.

example error in an .aux file due to bad \label declaration

The error Missing \endcsname inserted. at an \alpha may seem quite cryptic at first glance, and appears not to be that helpful in our debugging. But we see from the text (context) of the error message that it’s occurring somewhere near to some code that has sec:\alpha, which is associated with some label or counter numbered 1.1. Therefore, we may want to look carefully at any \label{...} in our .tex files that contain the snippet sec:\alpha.

You should soon find your way to line 37 of our example project:

\label{sec:\alpha}

The argument passed to \label{...} should not contain any LaTeX commands or control sequences, such as \alpha. Therefore, correcting the label to something like \label{sec:alpha}, as well as any corresponding \ref{...}, will clear this error.

Here’s another error reported from the .aux file, in our example project:

example error in an .aux file due to space in \cite{...} key

This time the compiler complains of a white space in a \citation; where the key starts with “That”. So we would want to search for \cite{That ...} in our .tex file... and we find it on line 23:

... justo \cite{That mandatory talk} eget magna ...

Citation keys should not contain space characters, so the spaces in this \cite{...}, as well as the corresponding BIBTeX key in the .bib file, should be removed.

Errors from .toc files

The .toc file contains entries for \tableofcontents. These are populated from sectional headings in a LaTeX document e.g., \chapter{...}, \section{...}, etc. Therefore, if you see errors reported from .toc files, it would be useful to check your sectional headings that contain text reported in the error message.

example error in an .toc file due to unescaped & in \section{...}

This looks like a sectional heading that would be numbered “1”, and contains the text Introduction & Welcome. A quick search in the .tex file will bring us to line 12:

\section{Introduction & Welcome}

The & is unescaped here, so we need to change it to \& in the .tex file.

Another similar example:

example error in an .toc file due to math command not in math mode in \section{...} key

Similarly our hunch would be to look for a sectional heading that would be numbered “1.1”, and likely containing Setting \alpha. Our hunch turns out to be correct, on line 36 of the .tex file:

\subsection{Setting \alpha}

\alpha is a math command but we forgot to put it in math mode here, so we need to correct this to

\subsection{Setting $\alpha$}

or

\subsection{Setting \(\alpha\)}

Sometimes the errors arise in the .toc file due to errors in the code used to style the entries in the table of contents:

example error in an .toc file due to improper code when styling the ToC entry

Here, searching with \itshae will lead us to a typo on line 5 of our example .tex: it should be \itshape instead. In this case the error can be located in the preamble of our .tex file, so we can go ahead and correct it. But if you are using a .cls or .sty file provided by your institution and you suspect the errors are due to misconfiguration in the provided files, you should contact the author or maintainer of the template or package so they can update the template.

Errors from .lof and .lot files

The .lof file contains entries for \listoffigures, and are populated by \caption{...} of figure environments.

Similarly, the .lot file uses \caption{...} from table environments, to generate entries for \listoftables.

Therefore, if there are LaTeX errors from .lof or .lot files, you should check the \caption{...} which contains the relevant text snippets.

Based on the error message here, we will search for Effects of \alpha and var_coeff in our \caption{...}s, especially for figures:

example error in an .lof file due to math command not in math mode in figure \caption{...} key

and come to line 19 in our .tex file:

\caption{Effects of \alpha and var_coeff}

The \alpha should be placed in math mode; and if var_coeff is supposed to be variable name, the underscore needs to be escaped. Don’t use \verb|var_coeff| because this can be quite disastrous in \caption{...}, too!

\caption{Effects of $\alpha$ and \texttt{var\_coeff}}

Similarly, looking at this error, we would search for some sample data with n^i in table \caption{...}, with a hunch that we forgot to put the n^i in math mode, too.

example error in an .lot file due to superscript not in math mode in table \caption{...} key

And so we correct line 31

\caption{Some sample data with n^i}

to

\caption{Some sample data with $n^i$}

Errors from .bbl files

The .bbl file contains entries for the reference list (bibliography), and is generated by BIBTeX after processing the .bib file, using styling information from the .bst file. Errors reported from .bbl usually originate from the .bib file.

Here’s a common error which we often see in Overleaf support:

example error in an .bbl file due to unescaped & in .bib file

Searching for This & that in the .bib file of the example project will land us on line 13, where we realise that the & should be escaped as \& or replaced with the word and.

    title   = {This & That},

Authors often encounter errors related to Unicode characters in .bbl (and therefore .bib) files—especially if the information sources had been copied-and-pasted from elsewhere:

example error in an .bbl file due to unsupported unicode character in .bib file

Copy-pasting the ♣ character from the error message and searching for it within the .bib file will bring you to line 3:

    title   = {Research ♣ Development},

Some Unicode characters are not supported by the latex and pdflatex compilers. To avoid the error, you may try changing your project’s compiler to XeLaTeX or LuaLaTeX. But even then you would need to ensure your project is compatible with those compilers, and that you have used a font which contains a glyph to represent ♣ so that it is rendered correctly in the output PDF. Therefore, it would be better to use the relevant LaTeX commands:

    title   = {Research $\clubsuit$ Development},

Sometimes, though, the character might be much harder to spot:

example error in an .bbl file due to unsupported, unprintable Unicode character in .bib file

Here, U+3000 is a Unicode Character IDEOGRAPHIC SPACE, and so indeed is a white space. It may be hard to copy this exact character from the error message so that you can search it in the .bib file. So we’ll have to try another way to locate it, by using a \DeclareUnicodeCharacter to replace U+3000 with something more visible! Add the following lines in your project’s preamble, before \begin{document}:

\usepackage{xcolor}
\DeclareUnicodeCharacter{3000}{\textcolor{red}{BAD!!}}

Compiling your project will then make the error disappear; but you should look carefully in the output PDF for the BAD!!:

output PDF replacing U+3000 with red BAD!!

So now we know that the bad character is between of and Wondrous, for the bibliography item by “An Author”. It looks quite innocuous on line 5 of the .bib file since it’s invisible: but if you retype that ...of Wondrous... manually with a normal space-bar, the error will go away after a recompile.

    journal = {Journal of Wondrous Musings},

A note about biblatex

If you are using the biblatex package, then similar errors in the .bib files would likely all be reported as coming from the \printbibliography line in your .tex file. The debugging process is similar: use the short text snippets in the error messages to search in your .bib file to locate the offending lines, and correct them.

Errors from .bst files

.bst files are bibliography styles that BIBTeX uses to process and format the reference list. If you see errors from .bst files, this might be due to bugs in the .bst itself, especially if it’s a very, very old style file that might no longer be compatible with recent LaTeX packages. But it may be actually due to errors in the .bib file, too. The most common error in this category looks like this:

Bst-error-example-01.png

The entry with BIBTeX key Someone:etal:2008 has the author field on line 12 of the .bib file:

    author  = {Strange Someone, Night Stranger, and Random Person},

In a .bib file, a list of multiple names should be separated by and, not commas nor &. Therefore this author field should be corrected to

    author  = {Strange Someone and Night Stranger and Random Person},

Errors from .ttt and .fff files

These file types are only generated if you load the endfloat package, which is used to force all table and figure environments to be moved to the end of the document, per the requirements of some academic journals during article submission.

To see example errors from these generated files, uncomment line 3 \usepackage{endfloat} of the .tex file in our example project.

Ttt-error-example-01.png

The .ttt file contain contents from all table environments in the document, so we would search for dummy & data in the .tex file, paying attention to tables. We would come to line 29 in the .tex file, where we see the problem: we have three columns, one more than the two declared. So one extra column may need to be deleted; or we should insert \\ after dummy to start a new row; or perhaps we had intended to declare three columns c | c | c after all!

Fff-error-example-01.png

Similarly, the .fff file contains content from all figure environments, and searching for that typo-ed \includegraphcs would bring us to line 18 of the .tex file, where we can correct it to \includegraphics.

Further Reading

Overleaf guides

LaTeX Basics

Mathematics

Figures and tables

References and Citations

Languages

Document structure

Formatting

Fonts

Presentations

Commands

Field specific

Class files

Advanced TeX/LaTeX