Fixing and preventing compile timeouts

When you click the Recompile button in your Overleaf project you start a process that reads your project files and converts them into a typeset PDF. If you hit a compile timeout error this means the compilation process couldn’t complete within the timeout limit for your Overleaf plan.

While it's possible that some projects are too large or complex to produce a PDF in the time provided, compile timeouts can often be fixed or prevented.

Steps to resolve compile timeouts

Follow these steps to identify and fix common issues that cause compile timeouts:

  1. Check for compile errors and fix them using Stop on First Error mode
  2. Try Fast[draft] mode and optimize your image sizes
  3. Assess your project for time-consuming tasks

In addition to following these steps, please review the suggestions about what to do in specific timeout situations as well as what best practices to follow to prevent compile timeouts.

While many projects can be compiled in the time provided on Overleaf's free plan, if you're preparing a large or complex document, you may need to subscribe to a premium plan to get more compile time.

Step 1: Check for compile errors and fix them

Some compile errors, or the build-up of several errors, can completely block the latexmk build process and lead to a compile timeout. To find and fix errors, turn on the Stop on first error compilation mode under the Recompile drop-down menu:

Screenshot showing how to enable the Stop on first error compilation mode

The Stop on first error compile mode does exactly what you'd expect—it stops compiling immediately when an error is hit. When this happens, no PDF is generated and a message describing the error will be shown. Turning on Stop on first error allows you to find and fix each error in the project until the project is error-free.

Clicking on each error message will bring you to the line in the source code that is causing the problem so that you can correct your code. Several common errors are explained on this page, and some LaTeX debugging suggestions are listed on this page. Please also see the section in this article that lists some common fatal compile errors that cause compile timeouts.

Step 2: Try compiling in Fast [draft] mode

Including many or large image files in your project can significantly add to the time required to compile your project.

One method that can help find out if image processing is the cause of the timeout is to try compiling in Fast [draft] mode. To do that, choose the Fast [draft] option from the Recompile menu. This replaces all of your graphics with boxes and makes the PDF compile much faster:

Setting draft compilation mode for an Overleaf project

If your document compiles in Fast [draft] mode but won't complete compile in Normal mode, the cause may be large or many image files.

Optimizing image files

If you've used multiple large, high-resolution PNG or JPEG files, processing those files can increase the time needed to compile your project, sometimes considerably. Be sure to:

  • Use PDF files instead of PNG files for diagrams and plots.
  • Reserve the use of JPEGs for photographs.

For additional advice see: Optimizing large image files.

Step 3: Assess your project for time-consuming tasks and fatal errors

If both Stop on First Error and Fast[draft] compile mode are still leading to a compile timeout, you may need to look further to identify the cause of the compile timeout and (hopefully) address it.

1. Review the list of time-consuming practices and packages that can slow down compilation

2. Review the list of common fatal errors that can lead to timeouts

3. Check the advice for specific timeout scenarios that best describes your situation

Time-consuming practices and packages

Some practices and packages can lead to very slow compiles, and even to timeouts.

Including 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 very time it makes a new PDF.

Using the mhchem package

Recent versions of the mhchem package can take longer to compile. Depending on what you are using it for, the chemformula package may reduce the time needed for compiling. 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.
Including tracing or debugging calls

If you happen to have a \tracingall command in your document, it may be writing a lot of data to the .log. Recording and processing \tracingall data in the .log file can cause compilation to become extremely slow. It is recommended to remove the \tracingall calls, or if you need to use similar methods for debugging to use the trace package instead.

Using the 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 a 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 that 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.

Using EPS or SVG images

The use of EPS or SVG images can require extra processing to convert them to PDF format. This extra processing will add to the time needed to compile your project.

  • While the latex compiler will support EPS images directly, the pdfLaTeX compiler does not  support EPS images, so an extra step is required to convert these to pdf images when that compiler is used. The processing is handled by the epstopdf package which uses Ghostscript to convert the EPS files to PDF. This conversion step can significantly add to the time required to compile the project.
  • SVG image files are not supported by any LaTeX compiler directly, and require the use of the svg package and the  \includesvg command that it provides. The svg package uses inkscape to convert SVG images to PDF.  This conversion step can significantly add to the time required to compile the project.

For faster results that may help to avoid compile timeouts, use PDF versions of your images instead of EPS or SVG formats.

Using the tabularray package

The tabularray package provides an alternative to the standard commands and environments for implementing tables in LaTex. Unfortunately the tabularray package runs very slowly, particularly for larger tables and those that use certain column types. Currently, standard table definition methods are recommended over tabularray because of compile time considerations.

Creating an infinite loop in a command

During compilation LaTeX commands can, very occasionally, trigger an “infinite loop.” Infinite loops are most commonly caused by bugs in packages or in user-defined commands.

If you suspect that you may be experiencing a loop, check to see if you accidentally created a recursive definition in one of your custom commands, such as \newcommand{\foo}{\foo}.

Some causes of fatal compile errors

Below are some known causes of fatal errors.

Including blank lines in sensitive titling commands

LaTeX classes and journal templates often provide special commands for providing parts of a document's title. These commands are usually meant to include simple arguments, and using them in unexpected ways can lead to compile errors and even timeouts. Most importantly, commands such as \author{...}, \date{...} and \title{...} should not contain blank lines.

Including too many fixed floats

If you have too many tables or figures using the [H] placement identifier from the float package, 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.

Errors in the \caption command 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.
Using the 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{...}.

Using the tikzpicture

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

Using the breqn package

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

Using the 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}).

Using the 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.

Advice for some specific timeout situations

My project was compiling without any errors, but now I am seeing a compile timeout

A small change can sometimes cause a compile timeout. To help identify the cause of the problem and fix it, try these steps:

  1. Use Recompile from Scratch to clear out any out-dated generated files that may causing problems.
  2. Use the Overleaf History feature to find your most recent changes. See the list of causes of fatal compile errors above.
  3. Use the Stop on First Error option to find and fix any error that you have introduced by accident.

It is possible that a small change has lead to a fatal compile error - please see the list of fatal compile errors above for some possible causes.

I just uploaded a project to Overleaf and I hit a compile timeout

It could be that your project is missing a key file or package, or that it is organized in a way that is causing problems for Overleaf's compile process.

  • If a project was compiled without problems on your local machine but fails to compile on Overleaf, it could be that you are using a different version of TeX Live on your own computer. You can change the version of Tex Live for your project to more closely match the one that has successfully compiled your project locally.
  • Your uploaded project may not have an optimal file-structure for Overleaf. If your main tex file is in a folder, the compiler may be having trouble locating some file dependencies. If your main tex file is in a folder, try restructuring your project so that the main tex file is at the top level of your project.

Following the instructions above for locating and fixing errors can often identify missing files, TeX Live version issues, and project organization problems.

I made a copy of a project that was compiling, but now I am hitting a compile timeout

New projects, including copies of existing projects, will use the latest version of TeX Live by default. If your original project was on an older version of TeX Live, it could be that there are incompatibilities with the most recent version that are causing problems. Try changing the TeX Live version on your new copy to match the version on the original project.

I can't get my project to compile when I include all the sections, but they each compile fine on their own

Follow the advice above on using the Fast[draft] compile option to see if the whole project can be compiled in Fast[draft] mode.

In some cases, it is possible to successfully compile a large project in two stages: first by running in Fast[draft] mode, and then by compiling in Normal mode.

Check each section of your project to identify possible sources of slow compiling. These may include large image files that can be optimized, or other time-consuming practices or packages.

My project times out sometimes, but it cannot compile reliably

Your project may be running very close to the maximum compile. Follow the advice above for fixing errors, optimising images, and avoiding time consuming practices or packages.

Best practices for preventing compile timeouts

It is much nicer to prevent compile timeouts from happening than having to deal with the sometimes stressful process of fixing them once they've occurred. These recommendations should help you prevent compile timeouts from happening, or quickly recover from them when they do.

Fix all compile errors when they happen

Compile errors are indicated by the red notification balloon next to the Recompile button as described on this page. If you click on the red balloon, you'll see the error messages. Clicking on each error message will bring you to the corresponding line in the source code, so that you can correct your code. We would recommend that errors be corrected as soon as possible, as letting them accumulate may lead to hard-to-debug and fatal errors in future.

This page explains several common compile errors. If you are having trouble understanding an error message, often searching online using the text from the error will take you to a blog or forum post where the error is explained and solutions are offered.

Label versions of your project before big changes or important milestones

Use the Overleaf History feature to label versions of your project, so you can easily compare your current project to earlier versions. This can help you quickly find any new sources of compile errors.

Organize your files

It is easier to find and fix problems if your project is well organized. In addition, good project management can allow you to compile specific sections of your project, making it easier to identify areas that may be contributing to extra long compiles. Please see here for advice on managing large projects.

More information on compiling and compile time

What is “compiling” anyway?

Compiling is the process of converting your LaTeX code to a typeset PDF file. Learn more about how Overleaf compiles LaTeX projects.

Fair use limits

Some large or complex documents may take a longer time to compile than the timeout limit on Overleaf's free plan, and may require the extended compile time that is available on our paid plans. Some projects may even need a longer compile time than is available on our paid plans. In those cases, you may need to download your project and compile it locally.

Still stuck?

If you have a compile timeout that you can't resolve using the advice here, please let us know.