YAML Directive Missing --- Document Start – How to Fix

Local only

A YAML directive section such as %YAML 1.2 must be followed by an explicit --- document start before ordinary document content begins.

22 chars · 2 lines

Waiting for input

Loading YAML parser…

YAML directive troubleshooting

How to fix a YAML directive missing the document start marker

The sample declares %YAML 1.2 and immediately starts a service mapping. Once a directive section is present, YAML expects --- to mark the start of the following document body. This tool is free to use. No account or payment is required.

Last updated

What you can do here

  • YAML 1.2 parser validation
  • Duplicate mapping key detection
  • Preloaded broken YAML example
  • Readable parser feedback
  • .yaml and .yml file import
  • Browser-local processing

Steps

  1. Find the %YAML or %TAG directive at the start of the stream.
  2. Add --- after the directive section before ordinary mappings, sequences, or scalars begin.
  3. Validate the complete stream and confirm the consumer actually supports the directive you kept.

Directives belong to a stream header, not the document body

Percent-prefixed directives provide parser instructions before a document. The explicit document start marker tells the parser where those instructions end and the data begins.

Most ordinary configuration files do not need a YAML directive

If a directive was copied from an example without a real compatibility requirement, removing it can be simpler. Keep it only when the consuming workflow benefits from the explicit stream metadata.

YAML directive without document start example

Insert --- between the %YAML directive and the service mapping.

Invalid YAML

%YAML 1.2
service: api

Corrected YAML

%YAML 1.2
---
service: api

Common questions

Frequently asked questions

What does --- mean in YAML?

It is the explicit document start marker and is required after a directive section before that document begins.

Do normal YAML files need %YAML 1.2?

Usually not. Many configuration files omit directives entirely and rely on the parser's supported YAML version.

Can several directives appear before one document?

A directive section may contain supported directives, but it still needs an explicit --- marker before document content starts.

Recommended next steps

Multiple YAML DocumentsDiagnose a YAML stream with more than one document when a single document is expected.Content After YAML Document EndStart a new document before content that follows the YAML ... end marker.YAML Validator Online – Check YAML SyntaxPaste any YAML document and inspect parser feedback locally.

Debugging a specific YAML issue? Browse YAML troubleshooting.