squidfunk/mkdocs-material · error · PluginError

Error reading meta file

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.

Solutions

1. Fix the YAML syntax in the `.meta.yml` at the path shown, using the appended yaml error for the line number
2. Replace tabs with spaces and use consistent 2-space indentation
3. Quote values containing special characters
4. 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

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:
    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

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

• Error reading layout file
• Error reading metadata of post
• Couldn't parse due to possible syntax error in HTML
• Error merging meta file
• Error reading authors file

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

Appendix: 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)