\begin{article}
LaTeX Compilation Timeouts in CI/CD: Causes, Fixes, and Plan Selection
LaTeX can take minutes to compile complex documents. Here is why, how to diagnose slow compilations, and how to configure timeouts correctly in your CI pipeline.
Nothing breaks a CI pipeline quite like a LaTeX job that runs for five minutes and then times out. Unlike most compilation steps that finish in seconds, LaTeX can legitimately take several minutes for complex documents — and the reasons are often surprising. This guide covers the causes, the fixes, and how to configure your pipeline accordingly.
Why LaTeX Is Slow
LaTeX is not a single-pass compiler. Complex documents require multiple passes, each of which reads the entire source file.
Multi-Pass Compilation
A document with cross-references, a table of contents, and a bibliography typically requires:
- Pass 1: Compile document, write
.auxfile with label positions - Pass 2: Compile again, read
.auxto resolve\ref{}and\pageref{} - Run BibTeX/Biber: Generate bibliography from
.bibfile and.aux - Pass 3: Compile again to incorporate bibliography
- Pass 4: Compile one more time to resolve bibliography references in text
That is four full passes through your entire document. A 100-page document with heavy math and bibliography can take 60–120 seconds even on fast hardware.
Font Loading
XeLaTeX and LuaLaTeX load OpenType fonts on startup. For documents with multiple custom fonts, this loading phase can add 10–30 seconds before the first page is rendered.
Package Initialization
Some packages do significant work on first use — tikz with complex diagrams, pgfplots with large datasets, and listings with syntax-highlighted code blocks all add compilation time.
The microtype Penalty
\usepackage{microtype} is excellent for output quality but adds 20–40% to pdflatex compilation time. For large documents on a free plan with a 30-second timeout, this can be the difference between success and timeout.
For CI pipelines where speed matters more than perfect typography, omit microtype or use \usepackage[draft]{microtype} to disable its processing without changing your source.
Common CI Timeout Causes
| Cause | Symptom | Solution |
|---|---|---|
| Bibliography not resolved | [?] in output, multiple biber runs | Use latexmk engine |
| Cross-references not resolved | ?? in output | Use latexmk engine |
Complex tikz diagrams | Slow on every compile | Externalize with tikz externalize |
| Large embedded images | Slow image encoding | Pre-compress images to PDF or PNG |
microtype on large docs | Consistently slow pdflatex | Use draft mode in CI |
| Font loading (XeLaTeX) | Slow startup | Cache font database with fc-cache |
Diagnosing Slow Compilations
Add timing to your LaTeX jobs:
time curl -X POST https://api.formatex.io/api/v1/compile \
-H "X-API-Key: $FORMATEX_KEY" \
-H "Content-Type: application/json" \
-d "{\"content\": $(cat document.tex | jq -Rs .), \"engine\": \"pdflatex\"}" \
--output document.pdf
# real 0m47.312s ← this tells you actual API round-trip timeIf compilation consistently exceeds 30 seconds on pdflatex, you need either:
- A plan upgrade for a longer timeout, or
- Document optimizations to reduce compilation time
Fixes for Self-Hosted Setups
If you are running pdflatex locally or on your own server, these fixes reduce compilation time. Keep in mind that self-hosting LaTeX vs. using a compilation API involves significant infrastructure overhead beyond just timeouts.
Use latexmk for Multi-Pass Documents
latexmk detects when re-runs are needed and stops as soon as the document is stable:
latexmk -pdf -interaction=nonstopmode document.texExternalize TikZ Diagrams
\usepackage{tikz}
\usetikzlibrary{external}
\tikzexternalize[prefix=tikz/]TikZ diagrams are compiled once and cached. On subsequent runs, cached diagrams are reused.
Draft Mode for Development
\documentclass[draft]{article}Draft mode skips image rendering and some expensive operations. Use it during development, disable for final output.
FormaTeX Timeout Tiers
FormaTeX enforces plan-specific timeouts. Choosing the right LaTeX compilation engine also affects how long each pass takes:
| Plan | Timeout | Best for |
|---|---|---|
| Free | 30s | Simple documents, short reports |
| Pro | 120s | Standard documents with bibliography |
| Max | 300s | Long-form, complex documents |
| Enterprise | 300s | High-volume, complex documents |
Choose your plan based on your typical document complexity.
Error Handling for Timeouts
When a compilation exceeds the timeout, the API returns:
{
"error": "compilation timeout",
"engine": "pdflatex",
"timeout_ms": 30000
}Handle this in your pipeline. For a full reference of all status codes your pipeline may encounter, see the LaTeX API error codes guide:
const response = await fetch("https://api.formatex.io/api/v1/compile", {
method: "POST",
headers: {
"X-API-Key": process.env.FORMATEX_KEY!,
"Content-Type": "application/json",
},
body: JSON.stringify({ content: latex, engine: "pdflatex" }),
});
if (!response.ok) {
const error = await response.json();
if (error.error === "compilation timeout") {
// Retry with latexmk or upgrade your plan
console.error(`Timeout after ${error.timeout_ms}ms. Consider upgrading your plan.`);
} else {
// Compilation error — check the log
console.error("LaTeX error:", error.log);
}
throw new Error(error.error);
}In shell-based pipelines, check the HTTP status code. Pairing this with API rate limiting and retry logic ensures your pipeline handles transient failures gracefully:
HTTP_STATUS=$(curl -s -o response.bin -w "%{http_code}" \
-X POST https://api.formatex.io/api/v1/compile \
-H "X-API-Key: $FORMATEX_KEY" \
-H "Content-Type: application/json" \
-d "{\"content\": $(cat document.tex | jq -Rs .), \"engine\": \"pdflatex\"}")
case "$HTTP_STATUS" in
200) mv response.bin document.pdf && echo "Success" ;;
408) echo "Compilation timeout — consider upgrading plan" && exit 1 ;;
400) echo "LaTeX error:" && cat response.bin | jq -r '.log' && exit 1 ;;
*) echo "API error: HTTP $HTTP_STATUS" && exit 1 ;;
esacThe Pro plan's 120-second timeout covers virtually all real-world documents including those with bibliography, TikZ diagrams, and complex math. Only extremely long theses and books typically require the Max plan's 300-second timeout.
Get Started
- Sign up for free — 30-second timeout, 15 compilations/month
- Pro plan — 120-second timeout, 500 compilations/month
- CI/CD integration guide — GitHub Actions, GitLab CI examples
Related Articles
- Compiling LaTeX in CI/CD Pipelines with FormatEx — Step-by-step GitHub Actions and GitLab CI integration using the FormatEx API
- The Complete Guide to LaTeX Engines — Understand pdfLaTeX, XeLaTeX, LuaLaTeX, and latexmk to pick the fastest engine for your document
- XeLaTeX vs pdfLaTeX — How font loading differences between engines affect compilation speed and timeout risk
- LaTeX API Error Codes: Complete Guide — Full reference for 408 timeout, 422 compile failure, 429 rate limit, and all other API errors
- LaTeX API Rate Limiting and Retry Logic — Exponential backoff and request queuing strategies to make CI pipelines resilient to timeouts
\end{article}
\related{posts}
