squidfunk/mkdocs-material · error · PluginError

Error reading metadata of post '{path}' in '{docs}': {e}

Error message

Error reading metadata of post '{path}' in '{docs}':
{e}

What it means

After extracting the post's YAML front-matter, the plugin parses it with `yaml.load(..., SafeLoader)`. If parsing fails for any reason (invalid YAML syntax, wrong types, tabs, duplicate keys, etc.), the caught exception is re-raised as this PluginError with the original yaml message appended, pointing the author to the offending post.

Source

Thrown at src/plugins/blog/structure/__init__.py:86

            # correctly implemented anyway. When using MultiMarkdown syntax, all
            # date formats are returned as strings and list are not properly
            # supported. Thus, we just use the relevants parts of `get_data`.
            match: Match = YAML_RE.match(self.markdown)
            if not match:
                raise PluginError(
                    f"Error reading metadata of post '{path}' in '{docs}':\n"
                    f"Expected metadata to be defined but found nothing"
                )

            # Extract metadata and parse as YAML
            try:
                self.meta = yaml.load(match.group(1), SafeLoader) or {}
                self.markdown = self.markdown[match.end():].lstrip("\n")

            # The post's metadata could not be parsed because of a syntax error,
            # which we display to the author with a nice error message
            except Exception as e:
                raise PluginError(
                    f"Error reading metadata of post '{path}' in '{docs}':\n"
                    f"{e}"
                )

            # Hack: if the meta plugin is registered, we need to move the call
            # to `on_page_markdown` here, because we need to merge the metadata
            # of the post with the metadata of any meta files prior to creating
            # the post configuration. To our current knowledge, it's the only
            # way to allow posts to receive metadata from meta files, because
            # posts must be loaded prior to constructing the navigation in
            # `on_files` but the meta plugin first runs in `on_page_markdown`.
            plugin: MetaPlugin = config.plugins.get("material/meta")
            if plugin:
                plugin.on_page_markdown(
                    self.markdown, page = self, config = config, files = None
                )

        # Initialize post configuration, but remove all keys that this plugin

View on GitHub (pinned to e2136532f4)

Solutions

  1. Read the appended yaml error message and fix the syntax at the indicated line in the post's front-matter
  2. Quote string values containing special characters (`title: "My: Post"`)
  3. Replace tabs with spaces and ensure consistent indentation
  4. Validate dates use ISO format, e.g. `date: 2024-01-15`

Example fix

# before
---
title: My: Post
date: 31.12.2024
---

// after
---
title: "My: Post"
date: 2024-12-31
---
Defensive patterns

Strategy: validation

Validate before calling

import yaml
from pathlib import Path
for p in Path('docs/posts').rglob('*.md'):
    text = p.read_text(encoding='utf-8-sig')
    if text.startswith('---'):
        block = text.split('---')[1]
        yaml.safe_load(block)  # raises with line info if invalid

Try / catch

try:
    mkdocs.commands.build(config)
except PluginError as e:
    if "Error reading metadata of post" in str(e):
        log.error(f"Fix YAML syntax in post front matter: {e}")
    raise

Prevention

When it happens

Trigger: A post's front-matter contains invalid YAML: unquoted colons in values, tabs for indentation, unclosed brackets/quotes, an invalid date value, or any construct the SafeLoader rejects.

Common situations: Hand-editing front-matter and breaking indentation; pasting values with special characters like `:` or `#` unquoted; YAML 1.1 syntax not accepted by the safe loader; malformed dates like `date: 31.12.2024`.

Related errors

AI-assisted analysis of squidfunk/mkdocs-material@e2136532f4 (2026-08-29). Data as JSON: /api/errors/faef459d28d76736. Report an issue: GitHub.