Skip to content

A pass that stops the build

A build runs Pandoc in passes: the main build, and for EPUB an expand pass that reads your book and expands it, and a collection of the fonts it uses, before it. A PDF's main build ends in XeLaTeX. When Pandoc or XeLaTeX stops a pass, Keystone closes with an ERROR: line naming it. A pass Keystone's own check stops ends on that check's ERROR: instead, under the ✗, with its own See link.

What it looks like

Publishing target: 'book' | format: pdf
  ✓ Preparing your artifact      1.5s
  ✓ Typesetting (pass 1)         22.1s
  ✓ Typesetting (pass 2)         19.8s
  ✓ Typesetting (pass 3)         16.5s
  ✗ Typesetting (pass 4)         16.2s
ERROR: publishing failed during the main build (format: pdf)
  │ Error producing PDF.
  │ ! Undefined control sequence.
  │ l.60 \undefinedmacro
  See https://keystone.knight-owl.dev/errors/build-stopped/

The ✗ names the stage the build stopped in. When Pandoc or XeLaTeX stopped it, the lines behind the │ bar say why.

What it means

Pandoc or LaTeX stopped it

In the example, XeLaTeX met a command it does not know. l.60 counts lines in the LaTeX Pandoc generated from your chapters, so the text after it is what to search your manuscript for. Raw LaTeX in a chapter is the usual cause. XeLaTeX runs every pass to its end and Pandoc judges only the last, so passes before it show ✓ even when the error was there from the first.

A ✗ on Reading your Markdown means Pandoc stopped before Keystone's stages, most often on a metadata block in a chapter that doesn't parse; the quote names the file and line. Metadata belongs in pandoc.yaml — see Metadata in a chapter.

A ✗ on Writing your artifact outside strict mode means Pandoc could not write the file, most often for a file it names that isn't there, such as a cover-image.

Fix what the quoted lines name

Search your manuscript for the text they quote. When they don't say enough, make publish progress=verbose shows the full log — see Watching a build run.

A warning in a strict build

Under strict mode, Pandoc refuses a pass that raised a warning once its work is done. The ✗ falls on the pass's last stage: the last Typesetting pass in a PDF, Writing your artifact in an EPUB, DOCX or ODT, and Finding your fonts for a warning Pandoc raises in the pass an EPUB reads its chapters in. Pandoc's reason is then Failing because there were warnings., and the WARN: above the ✗ is the cause.

Fix the warning above it

Its message names what to fix. The usual one in a PDF, Missing character, means the font has no glyph for a character you used; set a document font that has it.