# 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](https://docs.overleaf.com/getting-started/free-and-premium-plans/plan-limits). 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](#step-1-check-for-compile-errors-and-fix-them). 2. [Try **Fast \[draft\]** mode and optimize your image sizes](#step-2-try-compiling-in-fast-draft-mode). 3. [Assess your project for time-consuming tasks](#step-3-assess-your-project-for-time-consuming-tasks-and-fatal-errors). In addition to following these steps, please review the suggestions about what to do in [specific timeout situations](#advice-for-some-specific-timeout-situations) as well as what [best practices](#best-practices-for-preventing-compile-timeouts) 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](https://www.overleaf.com/user/subscription/plans) to get more compile time. {% stepper %} {% step %} ### 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](https://www.overleaf.com/learn/how-to/How_does_Overleaf_compile_my_project%3F) 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 of Stop On First Error setting selected
The [Stop on first error](https://docs.overleaf.com/troubleshooting-and-support/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](https://www.overleaf.com/learn/latex/Errors), and some LaTeX debugging suggestions are listed on [this page](https://docs.overleaf.com/troubleshooting-and-support/fixing-latex-errors). Please also see the [section in this article](#some-causes-of-fatal-compile-errors) that lists some common fatal compile errors that cause compile timeouts. {% hint style="success" %} Learn more about common [LaTeX errors](https://www.overleaf.com/learn/latex/Errors). {% endhint %} {% endstep %} {% step %} ### 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 determine 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:
Screenshot of Fast[draft] setting
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](https://docs.overleaf.com/troubleshooting-and-support/fixing-and-preventing-compile-timeouts/optimising-very-large-image-files). {% endstep %} {% step %} ### 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 root cause. 1\. [Review the list of time-consuming practices and packages that can slow down compilation](#time-consuming-practices-and-packages). 2\. [Review the list of common fatal errors that can lead to timeouts](#some-causes-of-fatal-compile-errors). 3\. [Check the advice for specific timeout scenarios that best describes your situation](#advice-for-some-specific-timeout-situations). #### **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`](https://ctan.org/pkg/pgfplots?lang=en) produce great graphics but they can [take a long time to compile](https://tex.stackexchange.com/a/254946/226). There are [several ways you can externalize the TikZ pictures](https://docs.overleaf.com/troubleshooting-and-support/fixing-and-preventing-compile-timeouts/reducing-the-compile-time-for-diagrams) so that LaTeX doesn’t have to redraw them every time it makes a new PDF. * **Using the `mhchem` package** Recent versions of the [`mhchem` package](https://ctan.org/pkg/mhchem?lang=en) can take longer to compile. Depending on what you are using it for, the [`chemformula` package](https://ctan.org/pkg/chemformula) may reduce the time needed for compiling. If you’ve already been using `mhchem`, you can try to drop-in `chemformula` as a replacement: ```latex % \usepackage{mhchem} \usepackage{chemformula} \let\ce\ch ```

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](http://ctan.org/pkg/trace) instead. * **Using the `acro` package** Users of the [`acro` package](https://www.ctan.org/pkg/acro) have [reported that version 3 is slow](https://github.com/cgnieder/acro/issues/205) 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](https://github.com/cgnieder/acro/releases/tag/v2.10). 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](https://github.com/cgnieder/acro/releases/tag/v2.10) 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](https://en.wikipedia.org/wiki/Recursion) 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](https://ctan.org/pkg/caption) is loaded, as demonstrated in the following example: ```latex \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**](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Overleaf+timeout+example\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cusepackage%7Bcaption%7D%0A%5Cbegin%7Bdocument%7D%0A%0A%5Cbegin%7Btable%7D%0A++++%5Cbegin%7Btabular%7D%7Bc%7Cc%7D%0A++++++++%5Ccaption%7BCaption%7D%25+%5Ccaption%7B...%7D+should+be+OUTSIDE+the+tabular+environment%0A++++++++a+%26+b+%5C%5C%0A++++++++c+%26+d+%5C%5C%0A++++%5Cend%7Btabular%7D%0A%5Cend%7Btable%7D%0A%5Cend%7Bdocument) * In contrast, note that the `longtable` environment *does* require `\caption{...}` within it, as demonstrated by an example in our [tables help article](https://www.overleaf.com/learn/latex/Tables#Multi-page_tables). * `\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](https://ctan.org/pkg/makecell?lang=en) if you’d like to add manual line breaks in a table cell, or the `p{...}` column type and/or [`tabularx`](https://ctan.org/pkg/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`](https://ctan.org/pkg/soul) or [`changes`](https://ctan.org/pkg/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 `tikzpicture`s. * **Using the `breqn` package**\ The [`breqn`](https://ctan.org/pkg/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`](https://ctan.org/pkg/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](https://github.com/compholio/jabbrv) to automatically abbreviate journal titles (see [this Overleaf example](https://www.overleaf.com/latex/templates/automatic-journal-abbreviations/mxfsdscmvxcr)). 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](https://docs.overleaf.com/getting-started/recompiling-your-project/selecting-a-tex-live-version-and-latex-compiler) to `XeLaTeX` or `LuaLaTeX`, both of which have built-in support for reading Unicode characters. {% endstep %} {% endstepper %} ## 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](https://docs.overleaf.com/troubleshooting-and-support/clearing-the-project-cache) to clear out any outdated generated files that may be causing problems. 2. Use the [Overleaf History feature](https://docs.overleaf.com/writing-and-editing/history-and-versioning) to find your most recent changes. See the list of causes of fatal compile errors above. 3. Use the [Stop on first error](https://docs.overleaf.com/troubleshooting-and-support/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](#some-causes-of-fatal-compile-errors) for some possible causes.
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](https://docs.overleaf.com/troubleshooting-and-support/clearing-the-project-cache) to clear out any outdated generated files that may be causing problems. 2. Use the [Overleaf History feature](https://docs.overleaf.com/writing-and-editing/history-and-versioning) to find your most recent changes. See the list of causes of fatal compile errors above. 3. Use the [Stop on first error](https://docs.overleaf.com/troubleshooting-and-support/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](#some-causes-of-fatal-compile-errors) 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](https://docs.overleaf.com/getting-started/recompiling-your-project/selecting-a-tex-live-version-and-latex-compiler) 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. 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](#step-1-check-for-compile-errors-and-fix-them) 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](https://docs.overleaf.com/getting-started/recompiling-your-project/selecting-a-tex-live-version-and-latex-compiler) 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](#step-2-try-compiling-in-fast-draft-mode) 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](#optimizing-image-files), or other [time-consuming practices or packages](#time-consuming-practices-and-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](#step-1-check-for-compile-errors-and-fix-them), [optimizing images](#optimizing-image-files), and [avoiding time-consuming practices or packages](#time-consuming-practices-and-packages).
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](https://docs.overleaf.com/troubleshooting-and-support/clearing-the-project-cache) to clear out any outdated generated files that may be causing problems. 2. Use the [Overleaf History feature](https://docs.overleaf.com/writing-and-editing/history-and-versioning) to find your most recent changes. See the list of causes of fatal compile errors above. 3. Use the [Stop on first error](https://docs.overleaf.com/troubleshooting-and-support/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](#some-causes-of-fatal-compile-errors) 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](https://docs.overleaf.com/getting-started/recompiling-your-project/selecting-a-tex-live-version-and-latex-compiler) 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. 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](#step-1-check-for-compile-errors-and-fix-them) 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](https://docs.overleaf.com/getting-started/recompiling-your-project/selecting-a-tex-live-version-and-latex-compiler) 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](#step-2-try-compiling-in-fast-draft-mode) 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](#optimizing-image-files), or other [time-consuming practices or packages](#time-consuming-practices-and-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](#step-1-check-for-compile-errors-and-fix-them), [optimizing images](#optimizing-image-files), and [avoiding time-consuming practices or packages](#time-consuming-practices-and-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](https://docs.overleaf.com/troubleshooting-and-support/fixing-latex-errors). 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](https://www.overleaf.com/learn/latex/Errors) 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](https://docs.overleaf.com/writing-and-editing/history-and-versioning) 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](https://www.overleaf.com/learn/latex/Management_in_a_large_project) 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](https://www.overleaf.com/learn/how-to/How_does_Overleaf_compile_my_project%3F).
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](https://www.overleaf.com/user/subscription/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](https://www.overleaf.com/contact).