Skip to content

Missing or invalid metadata

Your configuration is the metadata in pandoc.yaml, the target you're building and the output format. A problem in it is fatal, because there is no safe default: Keystone can't invent an abstract, guess which target you meant, write a format it doesn't support, or accept a value it can't interpret.

What it looks like

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

Publishing target: 'article' | format: pdf
  ✓ Expanding shortcuts          0.0s
ERROR: the target requires metadata this project does not set
  abstract (required for article)
  See https://keystone.knight-owl.dev/errors/missing-metadata/#a-required-field-isnt-set
  ✗ Resolving configuration      0.0s
ERROR: publishing failed during the main build (format: pdf)

The ✗ marks the stage the build stopped in — see Watching a build run. The other configuration failures:

ERROR: user-metadata.yaml is missing or empty (bind-mounted from pandoc.yaml)
  Make sure it exists and carries your document metadata.
  See https://keystone.knight-owl.dev/errors/missing-metadata/#the-metadata-file-is-missing-or-empty

ERROR: target metadata file not found: nonexistent.yaml
  Check 'target' in pandoc.yaml.
  See https://keystone.knight-owl.dev/errors/missing-metadata/#the-target-isnt-there

ERROR: unsupported format 'html'
  Valid: pdf, epub, docx, odt
  See https://keystone.knight-owl.dev/errors/missing-metadata/#the-format-isnt-one-keystone-writes

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'
  See https://keystone.knight-owl.dev/errors/missing-metadata/#a-value-it-cant-accept

What it means

A required field isn't set

Every target needs title and author; beyond that each asks for its own — an article an abstract, a scrbook a description.

Add the fields it names

Each one goes in pandoc.yaml. What a target requires is listed under Book metadata.

The metadata file is missing or empty

user-metadata.yaml is the name your pandoc.yaml is mounted under inside the build container, so the message names a file you won't find in your project.

Restore pandoc.yaml at your project root

An empty file trips this as surely as a missing one. What belongs in it is on Book metadata.

The target isn't there

target names a metadata file Keystone ships. A name it doesn't recognize resolves to nothing.

Check the name against the targets you have

The available layouts are on Targets.

The format isn't one Keystone writes

Pandoc writes many formats; the four Keystone offers are the ones its handlers and filters are tested against.

Build pdf, epub, docx or odt

The format is a build-time choice, not a setting in your source — see Output formats.

A value it can't accept

The same shape covers other rejected values with no page of their own — an xmp-metadata that isn't auto or disabled, an invalid or colliding marks: name.

Correct the value it names

Each setting's accepted form is documented with the setting, under Book metadata.

  • Missing required field — the same idea one layer in: a required attribute on an element, rather than a metadata field.