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
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
.
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 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.
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 tikzpicture
s.
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:
- Modify your project’s main
.tex
to: - change
\usepackage{acro}
to\usepackage{acro}[=v2]
- change the
include=...
option key of\printacronyms
toinclude-classes=...
- 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.
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:
Free plans | Paid plans | |
---|---|---|
Timeout | 1 minute | 4 minutes |
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.
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