What causes "Error reading meta file '{path}' in '{docs}': {e}" in squidfunk/mkdocs-material?

Fix the YAML syntax in the `.meta.yml` at the path shown, using the appended yaml error for the line number

squidfunk/mkdocs-material · error · PluginError

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

Error message

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

What it means

The `meta` plugin reads `.meta.yml` files during `on_files` and stores their parsed content. If a meta file fails to parse with the YAML SafeLoader (syntax error or other loader exception), the build aborts with this PluginError showing the underlying yaml error.

Source

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

        for file in files:
            name = posixpath.basename(file.src_uri)
            if not name == self.config.meta_file:
                continue

            # Exclude meta file from site directory - explicitly excluding the
            # meta file allows the author to use a file name without '.' prefix
            file.inclusion = InclusionLevel.EXCLUDED

            # Open file and parse as YAML
            with open(file.abs_src_path, encoding = "utf-8-sig") as f:
                path = file.src_path
                try:
                    self.meta[path] = load(f, SafeLoader)

                # The meta file could not be loaded 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 meta file '{path}' in '{docs}':\n"
                        f"{e}"
                    )

    # Set metadata for page, if applicable (run earlier)
    @event_priority(50)
    def on_page_markdown(self, markdown, *, page, config, files):
        if not self.config.enabled:
            return

        # Start with a clean state, as we first need to apply all meta files
        # that are relevant to the current page, and then merge the page meta
        # on top of that to ensure that the page meta always takes precedence
        # over meta files - see https://t.ly/kvCRn
        meta = {}

        # Merge matching meta files in level-order
        strategy = Strategy.TYPESAFE_ADDITIVE

View on GitHub (pinned to e2136532f4)

Solutions

Fix the YAML syntax in the `.meta.yml` at the path shown, using the appended yaml error for the line number
Replace tabs with spaces and use consistent 2-space indentation
Quote values containing special characters
Validate the file with `python -c "import yaml;yaml.safe_load(open('.meta.yml'))"`

Example fix

# before (.meta.yml)
title: Section: Intro
	description: bad tab

// after
title: "Section: Intro"
description: no tab here

Defensive patterns

Strategy: validation

Validate before calling

import yaml
from pathlib import Path
for p in Path('docs').rglob('.meta.yml'):
    yaml.safe_load(p.read_text(encoding='utf-8'))  # raises with line info

Try / catch

try:
    mkdocs.commands.build(config)
except PluginError as e:
    if "Error reading meta file" in str(e):
        log.error(f"Fix YAML syntax in the .meta.yml file: {e}")
    raise

Prevention

Lint all .meta.yml files with a YAML validator in CI
Use spaces (not tabs) and 2-space indentation in meta files
Quote values containing `:` or `#`
Validate meta files after any hand edit

When it happens

Trigger: A `.meta.yml` file in the docs directory contains invalid YAML: bad indentation, tabs, unquoted special characters, unclosed quotes/brackets, or duplicate keys rejected by the loader.

Common situations: Hand-editing `.meta.yml` and breaking indentation; pasting content with `:` or `#` unquoted; editor auto-converting spaces to tabs; copy-paste artifacts from documentation.

Related errors

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