{"record":{"id":"bec02a48233f131a","repo":"squidfunk/mkdocs-material","slug":"error-merging-meta-file-path-in-docs-e","errorCode":null,"errorMessage":"Error merging meta file '{path}' in '{docs}':\n{e}","messagePattern":"Error merging meta file '(.+?)' in '(.+?)':\n(.+?)","errorType":"exception","errorClass":"PluginError","httpStatus":null,"severity":"error","filePath":"src/plugins/meta/plugin.py","lineNumber":108,"sourceCode":"\n            # Skip if meta file was already merged - this happens in case of\n            # blog posts, as they need to be merged when posts are constructed,\n            # which is why we need to keep track of which meta files are applied\n            # to what pages using the `__extends` key.\n            page.meta.setdefault(\"__extends\", [])\n            if path in page.meta[\"__extends\"]:\n                continue\n\n            # Try to merge metadata\n            try:\n                merge(meta, defaults, strategy = strategy)\n                page.meta[\"__extends\"].append(path)\n\n            # Merging the metadata with the given strategy resulted in an error,\n            # which we display to the author with a nice error message\n            except Exception as e:\n                docs = os.path.relpath(config.docs_dir)\n                raise PluginError(\n                    f\"Error merging meta file '{path}' in '{docs}':\\n\"\n                    f\"{e}\"\n                )\n\n        # Ensure page metadata is merged last, so the author can override any\n        # defaults from the meta files, or even remove them entirely\n        page.meta = merge(meta, page.meta, strategy = strategy)\n\n# -----------------------------------------------------------------------------\n# Data\n# -----------------------------------------------------------------------------\n\n# Set up logging\nlog = logging.getLogger(\"mkdocs.material.meta\")\n","sourceCodeStart":90,"sourceCodeEnd":123,"githubUrl":"https://github.com/squidfunk/mkdocs-material/blob/e2136532f40aed98af1f6497c0cc6a3cff9f759b/src/plugins/meta/plugin.py#L90-L123","documentation":"When the meta plugin applies a `.meta.yml` file to a page during `on_page_markdown`, the merge strategy (e.g. deep merge of metadata) can raise if the data shapes are incompatible. Such exceptions are wrapped in this PluginError naming the meta file, docs dir, and original message.","triggerScenarios":"A `.meta.yml` defines a key whose value conflicts with the page's existing metadata during merging — e.g. a dict merged into a scalar or list, or the `__extends` mechanism referencing incompatible data — causing the merge implementation to throw.","commonSituations":"A page defines `tags: foo` (string) while `.meta.yml` defines `tags` as a list (or vice versa); nested metadata keys of mismatched shapes; custom merge strategies receiving unexpected types.","solutions":["Make the value types for the conflicting key consistent between the `.meta.yml` and the page front-matter (both lists or both dicts)","Read the appended message to identify which key fails to merge and align its structure","Simplify the meta file to only shared defaults and let pages override scalars explicitly"],"exampleFix":"# before (.meta.yml)\ntags:\n  - a\n# page has: tags: a\n\n// after (page)\ntags:\n  - a","handlingStrategy":"try-catch","validationCode":"import yaml\n# Ensure keys shared between .meta.yml and page front matter have the same shapes\nmeta = yaml.safe_load(Path('docs/sub/.meta.yml').read_text())\npage = yaml.safe_load(Path('docs/sub/page.md').read_text().split('---')[1])\nfor k in set(meta) & set(page):\n    assert type(meta[k]) == type(page[k]), f\"key '{k}' type mismatch\"\n","typeGuard":null,"tryCatchPattern":"try:\n    mkdocs.commands.build(config)\nexcept PluginError as e:\n    if \"Error merging meta file\" in str(e):\n        log.error(f\"Align metadata types between page and meta file: {e}\")\n    raise\n","preventionTips":["Keep value types for the same key consistent across .meta.yml files and page front-matter (e.g. tags always as a list)","Store only simple defaults (strings, lists of strings) in meta files","After changing merge strategies or plugin versions, rebuild and check a sample page","Document per-directory meta file conventions for the team"],"tags":["mkdocs","meta-plugin","merge-conflict","metadata"],"backgroundTag":"merge-type-conflict","analyzedSha":"e2136532f40aed98af1f6497c0cc6a3cff9f759b","analyzedAt":"2026-08-29T11:20:04.299Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}