Using the Stop on First Error compilation mode

This article explains how to use Overleaf’s Stop on first error compilation mode, together with reviewing some important background topics, including:

• What is a LaTeX compilation mode?
• Compilation modes on Overleaf
• How Stop on first error can be useful for debugging

To skip the background information you can jump straight to the section explaining how to enable the Stop on first error compilation mode.

Introduction to LaTeX errors and compilation

Conversion of a LaTeX document to a typeset PDF file is the result of a process called compilation: an executable program, known as a “LaTeX compiler”, reads the content of your document and executes its constituent LaTeX commands to generate the typeset PDF file.

When writing LaTeX markup (code) it is quite natural to make mistakes which, during compilation, cause the compiler to issue error messages that try to explain what the compiler thinks has caused the problem(s). As with other programming languages, a single mistake in your document’s LaTeX code can trigger a cascade of errors, each with its corresponding message. On Overleaf, compilation error messages are reported to the user via a red notification next to the Recompile button, and you can click on the Logs and output files icon to view them.

Handling errors: compilation modes

LaTeX compilers, also known as TeX engines, have built-in (user-selectable) compilation modes which determine how errors are handled. The following bulleted list uses Overleaf’s own explanatory/descriptive name for each of those modes:

• Try to compile despite errors—in essence, keep trying to compile despite encountering errors, hoping for the best, possibly producing a PDF file but one which may contain typesetting errors.
• Stop on first error—in effect “bail out” at the first sign of trouble, provide a message to the user and quit without creating a PDF. This avoids triggering a subsequent cascade of errors, letting you focus on fixing the very first error and recompiling the document.
• Suspend compilation to interact with the user—pause compilation to offer help and provide mechanisms for users to fix errors and continue compilation. This is possible with a local LaTeX installation but impractical on Overleaf.

Compilation modes on Overleaf

To manage LaTeX’s compilation process, Overleaf uses a build tool called latexmk which, by default, uses a compilation mode that Overleaf refers to as Try to compile despite errors: the build tool will try to produce a typeset PDF, even if there are LaTeX compile errors.

In the Try to compile despite errors compilation mode the LaTeX compiler does not stop if errors are detected; instead, it attempts to “best guess” the user’s intention and applies “fixes” based on that guess—problematic code may also be “skipped”. The compiler might return to a state where the compilation process can eventually complete to create a PDF, although the PDF produced may contain incorrect output. Often, the errors encountered may be too serious, or numerous, for the LaTeX compiler to fix so it might still “bail out” without producing a PDF.

Overleaf’s LaTeX error reporting

As noted above, error messages generated during compilation are reported to the user via a red notification next to the Recompile button:

You can click on the Logs and output files icon to view more detail on the error(s). For example, if you had mistakenly typed \texbf{word} instead of \textbf{word}, Overleaf would still show a compiled PDF preview along with the error message about the undefined command, but “word” would not be bold in the PDF!

The Stop on first error compilation mode

Users can now change the LaTeX compilation mode by switching to the Stop on first error mode which causes Overleaf to terminate compilation immediately upon detection of the first error.

How to enable Stop on first error

Select the small triangle next to the Recompile button then choose Stop on first error from the Recompile drop-down menu:

Scope of this mode setting

The Stop on first error mode is a per-user, per-project setting. Enabling this mode will not affect your other projects, or any collaborators in the same project.

Disabling Stop on first error

When Stop on first error is enabled, you can switch back to the default compilation mode by selecting the blue button Disable “Stop on first error” located in the dialog box which appears when there’s a compile error:

You can also go to the Recompile drop-down menu, and select the Try to compile despite errors mode:

Additional notes and advice

If your project is free from LaTeX compile errors, a PDF preview will be shown as usual. If your project does contain LaTeX compile errors, the compilation will stop immediately at the first error. The first error message is displayed as shown in the screenshot below, so that you can concentrate on debugging the error in your source code. In this screenshot, the error is due to incorrect use of \caption{...}\label{...} inside a tabular environment. Line 15 should be moved to before \begin{tabular}.

Click on Recompile after correcting each error, and then repeat this debugging process for each subsequent compile error. When your project is free of LaTeX errors, the Stop on first error mode will show the successfully compiled PDF.

Benefits of using the Stop on first error mode

• Helps to debug compile timeouts. Some types of compile errors are so serious (e.g., accidental recursion) they can block the Try compiling despite errors compilation mode, leading to a compile timeout in an Overleaf project. Enabling the Stop on first error mode may help to locate and debug such errors.
• Don’t let your errors pile up. Some users may prefer the behaviour of other LaTeX editors in which the compilation process will stop at the first LaTeX error encountered so they can correct the error before recompiling. Preventing errors from cascading—triggering an avalanche of further errors—avoids having to debug 100+ compile error messages which can become difficult and somewhat tedious.
• Enabling the Stop on first error mode can quickly detect your errors (if any). If you have a large or complex document that takes longer to compile, the Try to compile despite errors mode requires you to wait until the compilation finishes. If there are errors you need to fix it can be time-consuming having to wait before you can see the first compile error and attempt to fix it.
• Learning to debug errors is an essential part of learning LaTeX. The Stop on first error mode can help LaTeX beginners learn and adopt good LaTeX coding habits early on, perhaps hastening their journey to LaTeX proficiency. LaTeX errors can seem so bizarre and esoteric that it’s very tempting to ignore them and let the compiler carry on—hoping that a PDF will eventually appear, even if that PDF contains typesetting errors. In the long run, ignoring compilation errors can lead to bad coding habits which could, eventually, catch you out in future, perhaps during the submission of an important journal paper! If you’re teaching a class on LaTeX, your students can use the Stop on first error mode to develop skills in debugging LaTeX errors.

Errors which don’t seem to arise within your files

If you manually stop compilation in the Try to compile despite errors mode, then enable Stop on first error, the next compilation may result in some seemingly random error messages, such as ! File ended while scanning use of \@writefile, that don’t seem to originate from within your files. Such errors may be due to truncated files generated by, and left over from, the previous incomplete compilation. In that case, you may want to do a Recompile from Scratch so the next compilation, still in Stop on first error mode, has a chance to start from a clean slate and show the first pertinent error. If you’re still getting errors from a seemingly non-existent file—e.g., output.aux, output.toc etc.—have a look at this help page.

Some lower-level details

The Try to compile despite errors compilation mode runs latexmk with the following flags:

latexmk -f -interaction=nonstopmode …

The Stop on first error compilation mode will run latexmk with the following flags instead:

latexmk -halt-on-error -interaction=nonstopmode …

While you’re here, you might also be interested in reading more about how Overleaf uses the latexmk tool.