Skip to content

Missing or invalid metadata

Before Keystone touches your manuscript it resolves your configuration — the metadata in pandoc.yaml, the target you're building, the output format. A problem here stops the build up front, with a message that names what to fix.

What it looks like

The most common case — a field the target requires isn't set:

Publishing target: 'article' | format: pdf
ERROR: Missing required metadata fields:
  - abstract (required for article)
ERROR: publishing failed during the main build (format: pdf)

Which fields are required depends on the target (an article needs an abstract; a scrbook needs a description). The other configuration failures from this stage:

ERROR: user-metadata.yaml is missing or empty (bind-mounted from pandoc.yaml)
  Ensure it exists and contains your document metadata

ERROR: Target metadata file not found: nonexistent.yaml
  Check 'target' in pandoc.yaml

ERROR: Unsupported format 'html'. Use: pdf, epub, docx, or odt

And a metadata value Keystone doesn't accept — it names the key and the value:

ERROR: draft-scale must be a positive number, got: 0

The same shape covers other rejected values, such as an xmp-metadata that isn't auto or disabled, or an invalid or colliding marks: name.

What it means

These are all configuration errors, not content ones — they come from your pandoc.yaml, not your manuscript. They're fatal because there's no safe default: Keystone can't invent an abstract, guess which target you meant, build a format it doesn't support, or accept a value it can't interpret. (user-metadata.yaml is the name your pandoc.yaml is mounted under inside the build container — an empty or missing pandoc.yaml is what trips that one.)

How to fix

  • Missing required fields — add each named field to pandoc.yaml. Which fields a target requires is listed under Book metadata.
  • Unknown target — check the target value against the available targets.
  • Unsupported format — use one of pdf, epub, docx, odt; see Output formats.
  • Rejected value — correct the value the message names; each setting's accepted form is documented with it under Book metadata.
  • Missing required field — the same idea one layer in: a required attribute on an element, rather than a metadata field.