squidfunk/mkdocs-material · error · PluginError

Error merging meta file '{path}' in '{docs}': {e}

Error message

Error merging meta file '{path}' in '{docs}':
{e}

What it means

When the meta plugin applies a `.meta.yml` file to a page during `on_page_markdown`, the merge strategy (e.g. deep merge of metadata) can raise if the data shapes are incompatible. Such exceptions are wrapped in this PluginError naming the meta file, docs dir, and original message.

Source

Thrown at src/plugins/meta/plugin.py:108

            # Skip if meta file was already merged - this happens in case of
            # blog posts, as they need to be merged when posts are constructed,
            # which is why we need to keep track of which meta files are applied
            # to what pages using the `__extends` key.
            page.meta.setdefault("__extends", [])
            if path in page.meta["__extends"]:
                continue

            # Try to merge metadata
            try:
                merge(meta, defaults, strategy = strategy)
                page.meta["__extends"].append(path)

            # Merging the metadata with the given strategy resulted in an error,
            # which we display to the author with a nice error message
            except Exception as e:
                docs = os.path.relpath(config.docs_dir)
                raise PluginError(
                    f"Error merging meta file '{path}' in '{docs}':\n"
                    f"{e}"
                )

        # Ensure page metadata is merged last, so the author can override any
        # defaults from the meta files, or even remove them entirely
        page.meta = merge(meta, page.meta, strategy = strategy)

# -----------------------------------------------------------------------------
# Data
# -----------------------------------------------------------------------------

# Set up logging
log = logging.getLogger("mkdocs.material.meta")

View on GitHub (pinned to e2136532f4)

Solutions

1. Make the value types for the conflicting key consistent between the `.meta.yml` and the page front-matter (both lists or both dicts)
2. Read the appended message to identify which key fails to merge and align its structure
3. Simplify the meta file to only shared defaults and let pages override scalars explicitly

Example fix

# before (.meta.yml)
tags:
  - a
# page has: tags: a

// after (page)
tags:
  - a

import yaml
# Ensure keys shared between .meta.yml and page front matter have the same shapes
meta = yaml.safe_load(Path('docs/sub/.meta.yml').read_text())
page = yaml.safe_load(Path('docs/sub/page.md').read_text().split('---')[1])
for k in set(meta) & set(page):
    assert type(meta[k]) == type(page[k]), f"key '{k}' type mismatch"

try:
    mkdocs.commands.build(config)
except PluginError as e:
    if "Error merging meta file" in str(e):
        log.error(f"Align metadata types between page and meta file: {e}")
    raise

When it happens

Trigger: A `.meta.yml` defines a key whose value conflicts with the page's existing metadata during merging — e.g. a dict merged into a scalar or list, or the `__extends` mechanism referencing incompatible data — causing the merge implementation to throw.

Common situations: A page defines `tags: foo` (string) while `.meta.yml` defines `tags` as a list (or vice versa); nested metadata keys of mismatched shapes; custom merge strategies receiving unexpected types.

Related errors

• Error reading meta file '{path}' in '{docs}': {e}
• Relative path processor not registered
• Error reading filter configuration in '{key}': {e}
• Unknown shortcode: {type}
• Unknown type: {type}

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