squidfunk/mkdocs-material · error · PluginError

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

Error message

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

What it means

After parsing the front-matter, the Post class validates its option schema via `self.config.validate()`. Each entry in the resulting errors list (option key plus error message) aborts the build with this PluginError, naming the specific metadata key that failed validation.

Source

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

                    self.markdown, page = self, config = config, files = None
                )

        # Initialize post configuration, but remove all keys that this plugin
        # doesn't care about, or they will be reported as invalid configuration
        self.config: PostConfig = PostConfig(file.abs_src_path)
        self.config.load_dict({
            key: self.meta[key] for key in (
                set(self.meta.keys()) &
                set(self.config.keys())
            )
        })

        # Validate configuration and throw if errors occurred
        errors, warnings = self.config.validate()
        for _, w in warnings:
            log.warning(w)
        for k, e in errors:
            raise PluginError(
                f"Error reading metadata '{k}' of post '{path}' in '{docs}':\n"
                f"{e}"
            )

        # Excerpts are subsets of posts that are used in pages like archive and
        # category views. They are not rendered as standalone pages, but are
        # rendered in the context of a view. Each post has a dedicated excerpt
        # instance which is reused when rendering views.
        self.excerpt: Excerpt = None

        # Initialize authors and actegories
        self.authors: list[Author] = []
        self.categories: list[Category] = []

        # Ensure template is set or use default
        self.meta.setdefault("template", "blog-post.html")

        # Ensure template hides navigation

View on GitHub (pinned to e2136532f4)

Solutions

  1. Fix the metadata key named in the message to match the expected type/format shown in the appended error
  2. Use ISO 8601 dates (`date: 2024-01-15`) and correct value types
  3. Check the blog plugin documentation for the valid option names and value types
  4. If caused by an upgrade, review the changelog for changed post metadata schema

Example fix

# before
---
title: My Post
date: January 5, 2024
categories: Tutorials
---

// after
---
title: My Post
date: 2024-01-05
categories:
  - Tutorials
---
Defensive patterns

Strategy: validation

Validate before calling

import yaml, datetime
REQUIRED = {'title': str, 'date': (datetime.date, datetime.datetime)}
for p in Path('docs/posts').rglob('*.md'):
    text = p.read_text(encoding='utf-8-sig')
    meta = yaml.safe_load(text.split('---')[1])
    for k, t in REQUIRED.items():
        assert k in meta and isinstance(meta[k], t), f"{p}: bad metadata '{k}'"

Type guard

def has_valid_key(meta, key, expected_type):
    return key in meta and isinstance(meta[key], expected_type)

Try / catch

try:
    mkdocs.commands.build(config)
except PluginError as e:
    if "Error reading metadata" in str(e):
        key = str(e).split("metadata '")[1].split("'")[0]
        log.error(f"Fix '{key}' in the post front matter: {e}")
    raise

Prevention

When it happens

Trigger: A metadata key in a post's front-matter has a value of the wrong type or format, e.g. `date` not a valid date, `slug` not a string, unknown/invalid values for keys like `draft`, `readtime`, or `categories` of unexpected shape.

Common situations: Writing `date: January 5, 2024` instead of an ISO date; giving a list where a string is expected; misspelling an enum-like option value; schema changes after upgrading mkdocs-material.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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