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:
- Check for compile errors and fix them using Stop on First Error mode
- Try Fast[draft] mode and optimize your image sizes
- 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:
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:
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
andchemformula
, so this may not always work well. For example,\ce{2H2O}
will render fine withmhchem
, but withchemformula
you’ll have to write this as\ch{2 H2O}
with a space after the initial2
.
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:
- Modify your project’s main
.tex
to:- change
\usepackage{acro}
to\usepackage{acro}[=v2]
- change the
include=...
option key of\printacronyms
toinclude-classes=...
- change
- Within any
\DeclareAcronym
command, ensure thetag=...
option key is changed toclass=...
.
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 usesGhostscript
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. Thesvg
package usesinkscape
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.
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 thetabular
environment because it may cause fatal errors if thecaption
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}
- 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{...}
withintabular
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 themakecell
package if you’d like to add manual line breaks in a table cell, or thep{...}
column type and/ortabularx
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 tikzpicture
s.
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:
- Use Recompile from Scratch to clear out any out-dated generated files that may causing problems.
- Use the Overleaf History feature to find your most recent changes. See the list of causes of fatal compile errors above.
- 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.
Overleaf guides
- Creating a document in Overleaf
- Uploading a project
- Copying a project
- Creating a project from a template
- Using the Overleaf project menu
- Including images in Overleaf
- Exporting your work from Overleaf
- Working offline in Overleaf
- Using Track Changes in Overleaf
- Using bibliographies in Overleaf
- Sharing your work with others
- Using the History feature
- Debugging Compilation timeout errors
- How-to guides
- Guide to Overleaf’s premium features
LaTeX Basics
- Creating your first LaTeX document
- Choosing a LaTeX Compiler
- Paragraphs and new lines
- Bold, italics and underlining
- Lists
- Errors
Mathematics
- Mathematical expressions
- Subscripts and superscripts
- Brackets and Parentheses
- Matrices
- Fractions and Binomials
- Aligning equations
- Operators
- Spacing in math mode
- Integrals, sums and limits
- Display style in math mode
- List of Greek letters and math symbols
- Mathematical fonts
- Using the Symbol Palette in Overleaf
Figures and tables
- Inserting Images
- Tables
- Positioning Images and Tables
- Lists of Tables and Figures
- Drawing Diagrams Directly in LaTeX
- TikZ package
References and Citations
- Bibliography management with bibtex
- Bibliography management with natbib
- Bibliography management with biblatex
- Bibtex bibliography styles
- Natbib bibliography styles
- Natbib citation styles
- Biblatex bibliography styles
- Biblatex citation styles
Languages
- Multilingual typesetting on Overleaf using polyglossia and fontspec
- Multilingual typesetting on Overleaf using babel and fontspec
- International language support
- Quotations and quotation marks
- Arabic
- Chinese
- French
- German
- Greek
- Italian
- Japanese
- Korean
- Portuguese
- Russian
- Spanish
Document structure
- Sections and chapters
- Table of contents
- Cross referencing sections, equations and floats
- Indices
- Glossaries
- Nomenclatures
- Management in a large project
- Multi-file LaTeX projects
- Hyperlinks
Formatting
- Lengths in LaTeX
- Headers and footers
- Page numbering
- Paragraph formatting
- Line breaks and blank spaces
- Text alignment
- Page size and margins
- Single sided and double sided documents
- Multiple columns
- Counters
- Code listing
- Code Highlighting with minted
- Using colours in LaTeX
- Footnotes
- Margin notes
Fonts
Presentations
Commands
Field specific
- Theorems and proofs
- Chemistry formulae
- Feynman diagrams
- Molecular orbital diagrams
- Chess notation
- Knitting patterns
- CircuiTikz package
- Pgfplots package
- Typesetting exams in LaTeX
- Knitr
- Attribute Value Matrices
Class files
- Understanding packages and class files
- List of packages and class files
- Writing your own package
- Writing your own class