{"record":{"id":"e9cf76ef143d9535","repo":"squidfunk/mkdocs-material","slug":"error-reading-meta-file-path-in-docs-e","errorCode":null,"errorMessage":"Error reading meta file '{path}' in '{docs}':\n{e}","messagePattern":"Error reading meta file '(.+?)' in '(.+?)':\n(.+?)","errorType":"exception","errorClass":"PluginError","httpStatus":null,"severity":"error","filePath":"src/plugins/meta/plugin.py","lineNumber":68,"sourceCode":"        for file in files:\n            name = posixpath.basename(file.src_uri)\n            if not name == self.config.meta_file:\n                continue\n\n            # Exclude meta file from site directory - explicitly excluding the\n            # meta file allows the author to use a file name without '.' prefix\n            file.inclusion = InclusionLevel.EXCLUDED\n\n            # Open file and parse as YAML\n            with open(file.abs_src_path, encoding = \"utf-8-sig\") as f:\n                path = file.src_path\n                try:\n                    self.meta[path] = load(f, SafeLoader)\n\n                # The meta file could not be loaded because of a syntax error,\n                # which we display to the author with a nice error message\n                except Exception as e:\n                    raise PluginError(\n                        f\"Error reading meta file '{path}' in '{docs}':\\n\"\n                        f\"{e}\"\n                    )\n\n    # Set metadata for page, if applicable (run earlier)\n    @event_priority(50)\n    def on_page_markdown(self, markdown, *, page, config, files):\n        if not self.config.enabled:\n            return\n\n        # Start with a clean state, as we first need to apply all meta files\n        # that are relevant to the current page, and then merge the page meta\n        # on top of that to ensure that the page meta always takes precedence\n        # over meta files - see https://t.ly/kvCRn\n        meta = {}\n\n        # Merge matching meta files in level-order\n        strategy = Strategy.TYPESAFE_ADDITIVE","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/squidfunk/mkdocs-material/blob/e2136532f40aed98af1f6497c0cc6a3cff9f759b/src/plugins/meta/plugin.py#L50-L86","documentation":"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.","triggerScenarios":"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.","commonSituations":"Hand-editing `.meta.yml` and breaking indentation; pasting content with `:` or `#` unquoted; editor auto-converting spaces to tabs; copy-paste artifacts from documentation.","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'))\"`"],"exampleFix":"# before (.meta.yml)\ntitle: Section: Intro\n\tdescription: bad tab\n\n// after\ntitle: \"Section: Intro\"\ndescription: no tab here","handlingStrategy":"validation","validationCode":"import yaml\nfrom pathlib import Path\nfor p in Path('docs').rglob('.meta.yml'):\n    yaml.safe_load(p.read_text(encoding='utf-8'))  # raises with line info\n","typeGuard":null,"tryCatchPattern":"try:\n    mkdocs.commands.build(config)\nexcept PluginError as e:\n    if \"Error reading meta file\" in str(e):\n        log.error(f\"Fix YAML syntax in the .meta.yml file: {e}\")\n    raise\n","preventionTips":["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"],"tags":["mkdocs","meta-plugin","yaml","syntax-error"],"backgroundTag":"yaml-parse-error","analyzedSha":"e2136532f40aed98af1f6497c0cc6a3cff9f759b","analyzedAt":"2026-08-29T11:20:04.299Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}