squidfunk/mkdocs-material · error · PluginError

Error reading tags of page '{path}' in '{docs}': {e}

Error message

Error reading tags of page '{path}' in '{docs}':
{e}

What it means

The tags plugin's `on_page_markdown` reads tags from a page's markdown metadata inside a try/except; any underlying exception (bad meta syntax, YAML errors, invalid tag values) is re-raised as this PluginError annotated with the page path relative to the docs directory, so the build fails with a clear pointer to the offending page.

Source

Thrown at src/plugins/tags/plugin.py:183

            return

        # Handle deprecation of `tags_file` setting
        if self.config.tags_file:
            markdown = self._handle_deprecated_tags_file(page, markdown)

        # Handle deprecation of `tags_extra_files` setting
        if self.config.tags_extra_files:
            markdown = self._handle_deprecated_tags_extra_files(page, markdown)

        # Collect tags from page
        try:
            self.mappings.add(page, markdown)

        # Raise exception if tags could not be read
        except Exception as e:
            docs = os.path.relpath(config.docs_dir)
            path = os.path.relpath(page.file.abs_src_path, docs)
            raise PluginError(
                    f"Error reading tags of page '{path}' in '{docs}':\n"
                    f"{e}"
                )

        # Collect listings from page
        return self.listings.add(page, markdown)

    @event_priority(100)
    def on_env(
        self, env: Environment, *, config: MkDocsConfig, **kwargs
    ) -> None:
        """
        Populate listings.

        Priority: 100 (run earliest)

        Arguments:
            env: The Jinja environment.

View on GitHub (pinned to e2136532f4)

Solutions

  1. Open the page named in the error and validate its `tags:` front matter is a proper YAML list (`tags: [a, b]` or one-per-line with dashes).
  2. Run the markdown/YAML through a linter or `python -c "import yaml; yaml.safe_load(...)"` to find the syntax error detailed after the newline in the message.
  3. Check for typos in special tag prefixes (e.g. `hidden:`/shadow tags) if using tags plugin features.
  4. Ensure mkdocs.yml `plugins.tags` config matches the meta conventions of your installed version.

Example fix

# before
---
tags: mkdocs, guide
---

# after
---
tags:
  - mkdocs
  - guide
---
Defensive patterns

Strategy: validation

Validate before calling

import yaml, pathlib
def validate_tags(path):
    text = pathlib.Path(path).read_text()
    meta = text.split('---')[1] if text.startswith('---') else ''
    data = yaml.safe_load(meta) or {}
    tags = data.get('tags', [])
    assert isinstance(tags, list) and all(isinstance(t, str) for t in tags), f"{path}: tags must be a list of strings"

Type guard

def is_valid_tags(meta):
    tags = meta.get('tags')
    return tags is None or (isinstance(tags, list) and all(isinstance(t, str) for t in tags))

Try / catch

from mkdocs.exceptions import PluginError
try:
    markdown = plugin.on_page_markdown(markdown, page, config, files)
except PluginError as e:
    log.error(e)  # message already names the offending page and cause
    raise SystemExit(1)

Prevention

When it happens

Trigger: A page's `tags:` meta block contains invalid YAML or a non-list value; tags contain disallowed values shadowing listings; an exception occurs in `self.mappings.add(page, markdown)` while collecting tag mappings for the page.

Common situations: Hand-edited front matter with broken indentation; tags defined as a comma string instead of a YAML list; hidden/shadow tag syntax typos; a page converted from another system with non-standard meta.

Related errors

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