Fixing and avoiding compile timeouts

What is a “compile timeout”?

A compile timeout is triggered when the compilation process fails to complete within the timeout limit set by Overleaf—that limit depends on the type of plan you are using:

• free plans: timeout after 1 minute
• paid plans: timeout after 4 minutes

One of the reasons Overleaf applies compilation timeouts is to ensure fair resource allocation for all of our users.

What is “compiling”?

Compiling is the process of converting your LaTeX code, and figures, to a typeset PDF file. Many factors influence the time required to finish compiling a LaTeX document, including but not restricted to:

• size and complexity of the document and its content;
• bugs or incompatibilities in LaTeX packages or user-defined macros;
• “overhead’’ introduced by certain packages;
• the number and/or type of image files used in the document.

Some causes of compile timeouts and their fixes

The following sections list some common causes of compile timeouts together with strategies to avoid or fix them.

Using large, high-resolution images

Each time you compile a document LaTeX has to process any graphics files imported by that document—usually via the \includegraphics command. Image processing can include scaling, cropping or rotating any images in addition to extracting image data from graphics files and embedding it into the final typeset PDF file. If you have used multiple large, high-resolution PNG or JPEG files, processing those files can reduce the speed of compilation, sometimes considerably, so here are some options to address that:

• Use PDF files instead of PNG files for diagrams and plots and reserve the use of JPEG for images such as photographs.
• If your drawing or plotting software exports to PDF, use that rather than raster formats (PNG, JPEG etc) because compilation speeds are likely to improve and vector artwork will also look better (no jagged or fuzzy lines or text).
• Convert your PNG files to PDF before uploading them to your project: PDFs are much faster to process and compilation speed is likely to improve.
• Use draft mode when working online. To do that, select the downward-pointing arrow next to the Recompile button, and then choose the Fast [draft] option. This replaces all of your graphics with boxes and makes the PDF compile much faster:
  
  

• Use lower-resolution images for the online version of the document.
• For additional advice visit the Overleaf page on optimising large image files.

Complex TikZ or pgfplots drawings

TikZ and pgfplots produce great graphics but they can take a long time to compile. There are several ways you can externalize the TikZ pictures so that LaTeX doesn’t have to redraw them from scratch every time it makes a new PDF.

mhchem

Recent versions of the mhchem package can take longer to compile. Depending on your usage scenario, the chemformula package may enable faster compilation. If you’ve already been using mhchem, you can try to drop-in chemformula as a replacement:

% \usepackage{mhchem}
\usepackage{chemformula}
\let\ce\ch

• Note: there are syntax and feature differences between mhchem and chemformula, so this may not always work well. For example, \ce{2H2O} will render fine with mhchem, but with chemformula you’ll have to write this as \ch{2 H2O} with a space after the initial 2.

Tracing/debugging calls

If you happen to have a \tracingall command in your document, perhaps leftover from a template or a project from a local machine, it’ll be writing a lot of data to the .log file which can quickly grow to hundreds of MBs—with no sign of stopping! Recording and processing all that data in the .log file causes compilation to become extremely slow, so if you need to debug an Overleaf project we suggest removing the \tracingall call or use the trace package instead.

Infinite loops

During compilation LaTeX commands can, very occasionally, trigger an “infinite loop” whilst trying to create the typeset PDF: compilation will not finish, no matter how long you are prepared to wait. Infinite loops are most commonly caused by bugs in packages or in user-defined commands; for example, when a command’s definition calls (expands) to itself through a process called recursion. Such loops, triggered by accidental recursion, are another reason for Overleaf’s use of compile timeouts.

If you experience a loop, check to see if you accidentally created a recursive definition such as \newcommand{\foo}{\foo}.

Fatal compile errors blocking the compilation

Unfortunately, some LaTeX compile errors can completely block the latexmk build process and therefore lead to a timeout.

Troubleshooting using “Stop on first error”

To debug errors enable the Stop on first error compilation mode, accessible via the Recompile drop-down menu:

The Stop on first error compilation mode causes Overleaf to terminate compilation immediately upon detection of the first error, albeit without generating a PDF preview. You can then debug and correct each error you come across until the project is error-free. A PDF preview will then be shown. You can then switch back to the Try to compile despite errors mode, if you wish:

If you still get a timeout even in Stop on first error mode, it is likely that the main cause is one of the issues discussed in previous sections.

Other issues which can cause compilation timeouts

The following list, compiled by Overleaf’s user-support team, describes issues which have generated errors and triggered timeouts.

General issues

• \author{...}, \date{...} and \title{...} should not contain blank lines.
• If you have too many tables or figures using the [H] placement identifier, it may cause LaTeX to run into an infinite loop trying to find suitable places for all of them. Consider replacing all [H] with [hbt!] and if necessary an occasional \clearpage to flush out all tables and figures in the queue before inserting a page break.

\caption and tabular environments

Here is a list of table-related issues to be aware of—in general, try to be careful when typesetting tables!

• \caption{...} should always be placed outside the tabular environment because it may cause fatal errors if the caption package is loaded, as demonstrated in the following example:
  
  

  \documentclass{article}
  \usepackage{caption}
  \begin{document}
  
  \begin{table}
      \begin{tabular}{c|c}
          \caption{Caption}% \caption{...} should be OUTSIDE the tabular environment
          a & b \\
          c & d \\
      \end{tabular}
  \end{table}
  \end{document}
  

   Open this example which triggers an Overleaf timeout error

• In contrast, note that the longtable environment does require \caption{...} within it, as demonstrated by an example in our tables help article.
• \caption{...} should not contain \\, \newline, \centering, \raggedright etc.
• With some templates or packages, \ref{...} or \cite{...} within a \caption may need to be prefixed by \protect in order to avoid fatal errors; for example, \protect\cite{...}.
• Check for incomplete \cmidrule{...} within tabular environments; it requires a range of columns so you’ll need to write \cmidrule{3-3} instead of just \cmidrule{3} if you want a horizontal rule that spans only one column.
• Avoid nested tabular environments. Have a look at the makecell package if you’d like to add manual line breaks in a table cell, or the p{...} column type and/or tabularx package if you’re looking for ways to create columns that auto-wrap long lines.
• If you have tabular rows that start with [... you may need to add \relax after the \\ on the previous row.

soul or changes package

If you’re using the soul or changes package to highlight text or strike text out, then \cite and \ref may need to be prefixed by \protect; for example, \protect\cite{...}.

tikzpicture

Check for missing ; at the end of path/node commands and ] at the end of parameter lists in tikzpictures.

breqn package

The breqn package’s dmath environment may run into infinite loops; replace with align and manually break lines if necessary.

babel package

Some babel language options change the meaning of certain characters which can cause problems when those characters are used in their “normal” context; for example, in math mode. To avoid this, try using the option shorthands=off when loading babel (e.g., \usepackage[shorthands=off]{babel}).

jabbrv package

Some templates use the jabbrv package to automatically abbreviate journal titles (see this Overleaf example). When a journal field in the .bib file contains accented Unicode characters (e.g. Biología), this can block the compilation and cause a timeout on Overleaf. LaTeX commands need to be used instead, e.g. Biolog{\'i}a or you can change the project’s compiler to XeLaTeX or LuaLaTeX, both of which have built-in support for reading Unicode characters.

acro package

Users of the acro package have reported that version 3 is slow to load acronym declarations. One consequence of acro’s increased compilation time is the possibility of triggering an Overleaf compile timeout; fortunately, there is a workaround: using version 2 of the acro package.

Switching from version 3 back to version 2 may require editing your project to ensure it is compatible with version 2’s options, features and commands. Documentation for version 2 is available, contained within earlier source code releases which can be downloaded from GitHub.

Here are some items to check when reverting to version 2—this list is far from exhaustive:

1. Modify your project’s main .tex to:
• change \usepackage{acro} to \usepackage{acro}[=v2]
• change the include=... option key of \printacronyms to include-classes=...
2. Within any \DeclareAcronym command, ensure the tag=... option key is changed to class=....

Please refer to acro version 2.10’s documentation for commands and options available in version 2 but not in version 3.

Fair use limits

Some very large document and/or complex documents may, due to their very nature, take a long time to compile. To address that we offer longer compile times on our paid plans:

Still stuck?

If you have a compile timeout error that you cannot resolve, please let us know and we’ll take a look for you.