Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 38 ยท Beamer, Tooling and Workflows

TeX Engines, latexmk and Fixing Errors

Choose between pdfLaTeX, XeLaTeX and LuaLaTeX, automate builds with latexmk, read the log file and fix the most common LaTeX errors and warnings.

You can write LaTeX in any text editor, but the build is where most problems appear: the wrong engine, a missing second run, a stale auxiliary file, an error whose message points to the wrong line. This lesson explains the engines, how latexmk runs the whole chain, and how to read the log.

Engines

Engine Output Fonts and Unicode Typical use
latex DVI Legacy Old workflows, some PSTricks
pdflatex PDF Type 1 / OpenType via packages, UTF-8 input only Default, fastest, most compatible
xelatex PDF System fonts via fontspec, full Unicode Non-Latin scripts, custom fonts
lualatex PDF System fonts, Lua scripting, full Unicode Complex fonts, programmable layout

Choose pdfLaTeX unless you need system fonts, right-to-left scripts or Lua. Templates often require a specific engine. A magic comment at the top of the file tells editors which one to use:

LATEX
% !TEX program = xelatex

Overleaf has a compiler menu for the same purpose.

What a build actually involves

A document with citations, an index and cross-references needs a sequence of tools:

flowchart TD
  A["pdflatex: write .aux, .toc"] --> B["bibtex or biber: read .aux, write .bbl"]
  B --> C["makeindex / makeglossaries"]
  C --> D["pdflatex: insert lists"]
  D --> E["pdflatex: settle references"]
  E --> F["main.pdf"]

Doing this by hand is error prone; latexmk decides which steps are needed.

latexmk

latexmk is a Perl script included in TeX Live and MiKTeX. It reads the log, sees which files changed and reruns exactly the tools needed until the output is stable.

TEXT
latexmk -pdf main.tex           # pdfLaTeX
latexmk -xelatex main.tex       # XeLaTeX
latexmk -lualatex main.tex
latexmk -pdf -pvc main.tex      # watch mode: rebuild on every save
latexmk -pdf -interaction=nonstopmode -file-line-error main.tex
latexmk -c                      # clean auxiliary files, keep the PDF
latexmk -C                      # clean everything including the PDF

Useful options: -outdir=build writes all generated files in a folder; -shell-escape allows minted and the external TikZ library; -halt-on-error stops at the first problem.

A project configuration file .latexmkrc keeps settings with the project:

PERL
$pdf_mode = 1;                          # use pdflatex
$pdflatex = 'pdflatex -interaction=nonstopmode -synctex=1 %O %S';
$out_dir = 'build';
$bibtex_use = 2;                        # run bibtex/biber when needed, clean .bbl too

SyncTeX (-synctex=1) lets editors jump from a place in the source to the matching spot in the PDF and back.

The stand-in below scans a short log the way you will: it finds errors, warnings and the line numbers that matter.

JS Read a LaTeX log

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Reading errors

LaTeX errors have a standard look:

TEXT
! Undefined control sequence.
l.15 \includegraphcs
                    {plot.pdf}

The first line says what is wrong, the l.15 line gives the line number, and the text shows where TeX stopped reading. Fix the first error first; later ones are often consequences of it. With -file-line-error you get main.tex:15: prefixes that editors can click.

Frequent errors and fixes:

Message Usual cause
Undefined control sequence Typo or missing package
Missing $ inserted Math symbol or _ / ^ outside math mode
Missing } inserted, Runaway argument? Unbalanced braces
File 'x.sty' not found Package not installed
Environment foo undefined Typo or missing package
\begin{x} ended by \end{y} Mismatched environments
Paragraph ended before \x was complete Blank line inside an argument
Misplaced alignment tab character & & used outside a table; escape as \&
Option clash for package See using packages
LaTeX Error: Too many unprocessed floats Many figures with no text; add \clearpage
Dimension too large Plot or length overflow

Special characters that must be escaped: # $ % & _ { } \~{} \^{} \textbackslash.

Warnings worth attention

  • Reference ... undefined or Citation ... undefined: run again, or check keys (labels).
  • Overfull \hbox: a line is too wide; check the text near the reported lines.
  • Underfull \hbox (badness 10000): very loose spacing.
  • Font shape ... not available: substituted font.
  • Float too large for page: shrink the figure.
  • Label(s) may have changed. Rerun: run again.

Cleaning and cache problems

Weird errors that vanish after cleaning are usually stale auxiliary files. Delete .aux, .toc, .out, .bbl and .log, or run latexmk -C. If you use Overleaf, use "Recompile from scratch" from the menu next to the Recompile button.

Editors

  • Overleaf: online, nothing to install, real-time collaboration.
  • TeXstudio, TeXworks: all-in-one desktop editors.
  • VS Code with LaTeX Workshop: build, preview, SyncTeX, snippets and linting; set latex-workshop.latex.recipes.
  • Vim/Neovim with VimTeX, Emacs with AUCTeX: for keyboard-driven workflows.
  • Linting: chktex and lacheck catch common style mistakes; latexindent formats code.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which engine should you choose to use system TrueType fonts via fontspec?

    XeLaTeX and LuaLaTeX load system fonts and handle Unicode natively; pdfLaTeX does not.
  2. 2. What does latexmk -pdf -pvc main.tex do?

    -pvc is preview continuously: latexmk watches the files and recompiles when they change.
  3. 3. Which error should you fix first when several appear?

    Later errors are often caused by the first, so fixing from the top removes many at once.
  4. 4. What does 'Missing $ inserted' usually mean?

    TeX tried to typeset math-only characters in text mode, so it inserted a dollar sign to start math.

Summary

  • pdfLaTeX is the default; XeLaTeX and LuaLaTeX bring system fonts and full Unicode.
  • Documents with references need several runs; latexmk automates them, and .latexmkrc stores project settings.
  • Read the first error, its line number and the context; use -file-line-error.
  • Learn the common messages and escape special characters.
  • Clean stale auxiliary files when errors look strange.

Next: Version Control and Collaboration