{"record":{"id":"0af9e248820a11b6","repo":"squidfunk/mkdocs-material","slug":"error-reading-tags-of-page-path-in-docs","errorCode":null,"errorMessage":"Error reading tags of page '{path}' in '{docs}':\n{e}","messagePattern":"Error reading tags of page '(.+?)' in '(.+?)':\n(.+?)","errorType":"exception","errorClass":"PluginError","httpStatus":null,"severity":"error","filePath":"src/plugins/tags/plugin.py","lineNumber":183,"sourceCode":"            return\n\n        # Handle deprecation of `tags_file` setting\n        if self.config.tags_file:\n            markdown = self._handle_deprecated_tags_file(page, markdown)\n\n        # Handle deprecation of `tags_extra_files` setting\n        if self.config.tags_extra_files:\n            markdown = self._handle_deprecated_tags_extra_files(page, markdown)\n\n        # Collect tags from page\n        try:\n            self.mappings.add(page, markdown)\n\n        # Raise exception if tags could not be read\n        except Exception as e:\n            docs = os.path.relpath(config.docs_dir)\n            path = os.path.relpath(page.file.abs_src_path, docs)\n            raise PluginError(\n                    f\"Error reading tags of page '{path}' in '{docs}':\\n\"\n                    f\"{e}\"\n                )\n\n        # Collect listings from page\n        return self.listings.add(page, markdown)\n\n    @event_priority(100)\n    def on_env(\n        self, env: Environment, *, config: MkDocsConfig, **kwargs\n    ) -> None:\n        \"\"\"\n        Populate listings.\n\n        Priority: 100 (run earliest)\n\n        Arguments:\n            env: The Jinja environment.","sourceCodeStart":165,"sourceCodeEnd":201,"githubUrl":"https://github.com/squidfunk/mkdocs-material/blob/e2136532f40aed98af1f6497c0cc6a3cff9f759b/src/plugins/tags/plugin.py#L165-L201","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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).","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.","Check for typos in special tag prefixes (e.g. `hidden:`/shadow tags) if using tags plugin features.","Ensure mkdocs.yml `plugins.tags` config matches the meta conventions of your installed version."],"exampleFix":"# before\n---\ntags: mkdocs, guide\n---\n\n# after\n---\ntags:\n  - mkdocs\n  - guide\n---","handlingStrategy":"validation","validationCode":"import yaml, pathlib\ndef validate_tags(path):\n    text = pathlib.Path(path).read_text()\n    meta = text.split('---')[1] if text.startswith('---') else ''\n    data = yaml.safe_load(meta) or {}\n    tags = data.get('tags', [])\n    assert isinstance(tags, list) and all(isinstance(t, str) for t in tags), f\"{path}: tags must be a list of strings\"","typeGuard":"def is_valid_tags(meta):\n    tags = meta.get('tags')\n    return tags is None or (isinstance(tags, list) and all(isinstance(t, str) for t in tags))","tryCatchPattern":"from mkdocs.exceptions import PluginError\ntry:\n    markdown = plugin.on_page_markdown(markdown, page, config, files)\nexcept PluginError as e:\n    log.error(e)  # message already names the offending page and cause\n    raise SystemExit(1)","preventionTips":["Lint front matter with a markdown/YAML linter in pre-commit","Always write tags as a YAML list of strings","Run `mkdocs build --strict` in CI to catch meta problems early"],"tags":["mkdocs-material","tags-plugin","yaml","front-matter"],"backgroundTag":"invalid-front-matter","analyzedSha":"e2136532f40aed98af1f6497c0cc6a3cff9f759b","analyzedAt":"2026-08-29T11:20:04.299Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}