getgrav/grav · error · RuntimeException

Decoding YAML failed: {message}

Error message

Decoding YAML failed: {message}

What it means

YamlFormatter::decode() parses YAML with Symfony Yaml; a ParseException (syntax error in the document) is rethrown as 'Decoding YAML failed', but only after the optional 'compatible' fallback parser also fails or is disabled. It means the file's YAML is syntactically invalid for both the strict parser and (if enabled) the lenient one. The parse error message from Symfony names the exact line and offset.

Source

Thrown at system/src/Grav/Framework/File/Formatter/YamlFormatter.php:126

            @ini_set('yaml.decode_php', '0');
            $decoded = @yaml_parse($data);
            if ($saved !== false) {
                @ini_set('yaml.decode_php', $saved);
            }

            if ($decoded !== false) {
                return (array) $decoded;
            }
        }

        try {
            return (array) YamlParser::parse($data);
        } catch (ParseException $e) {
            if ($this->useCompatibleDecoder()) {
                return (array) FallbackYamlParser::parse($data);
            }

            throw new RuntimeException('Decoding YAML failed: ' . $e->getMessage(), 0, $e);
        }
    }
}

View on GitHub (pinned to 6040efed04)

Solutions

1. Open the file at the line/column given in the appended ParseException message and fix the syntax (quote the value, fix indentation).
2. Replace TAB indentation with spaces and remove any BOM (re-save as UTF-8 without BOM).
3. Validate with a YAML linter (yamllint, or bin/plugin symlinked checks) before deploying.
4. Enable the compatible decoder ('compatible' => true in formatter options) so minor legacy syntax still parses.

Example fix

# before (page frontmatter, tabs used)
title:	My Page

# after
title: "My Page"

// Pre-flight parse when users edit YAML (e.g. admin save hook)
use Grav\Framework\File\Formatter\YamlFormatter;
try {
    YamlFormatter::parse($raw); // or Symfony Component\Yaml\Yaml::parse($raw)
} catch (\Symfony\Component\Yaml\Exception\ParseException $e) {
    $admin->setMessage('YAML error at line ' . $e->getParsedLine() . ': ' . $e->getSnippet(), 'error');
}

try {
    $data = $formatter->decode($data);
} catch (\Grav\Framework\File\Formatter\Exception\RuntimeException $e) {
    // $e->getPrevious() is the ParseException with line/snippet info
    $line = $e->getPrevious() ? $e->getPrevious()->getParsedLine() : '?';
    throw new \RuntimeException("{$filename}: invalid YAML near line {$line}", 0, $e);
}

When it happens

Trigger: Loading a page/config file indented with TABs; unquoted values containing ': ' or starting with @ or `; duplicate top-level keys; a UTF-8 BOM at file start; truncated frontmatter after a failed edit or partial upload.

Common situations: Hand-editing page frontmatter in an editor that inserts tabs; a deploy pipeline or copy/paste stripping the closing --- delimiter; content authors pasting rich-text (smart quotes, non-breaking spaces) into YAML values.

Related errors

• Encoding YAML failed: {message}
• json_encode(): failed to encode dependencies
• Failed to load file '%s': %s
• CSV header missing
• Badly formatted CSV line: {line}

AI-assisted analysis of getgrav/grav@6040efed04 (2026-08-17). Data as JSON: /api/errors/55650d993fd94eb4. Report an issue: GitHub.