{"record":{"id":"00b77ee5acc66c0c","repo":"squidfunk/mkdocs-material","slug":"error-reading-listing-configuration-in-path","errorCode":null,"errorMessage":"Error reading listing configuration in '{path}':\n{e}","messagePattern":"Error reading listing configuration in '(.+?)':\n(.+?)","errorType":"exception","errorClass":"PluginError","httpStatus":null,"severity":"error","filePath":"src/plugins/tags/structure/listing/manager/__init__.py","lineNumber":374,"sourceCode":"                    f\"configurations: {keys}\"\n                )\n\n        # Otherwise, handle inline listing configuration\n        else:\n            config = ListingConfig(config_file_path = path)\n            config.load_dict(data or {})\n\n            # Validate listing configuration\n            errors, warnings = config.validate()\n            for _, w in warnings:\n                path = os.path.relpath(path)\n                log.warning(\n                    f\"Error reading listing configuration in '{path}':\\n\"\n                    f\"{w}\"\n                )\n            for _, e in errors:\n                path = os.path.relpath(path)\n                raise PluginError(\n                    f\"Error reading listing configuration in '{path}':\\n\"\n                    f\"{e}\"\n                )\n\n        # Inherit shadow tags configuration, unless explicitly set\n        if not isinstance(config.shadow, bool):\n            config.shadow = self.config.shadow\n\n        # Inherit layout configuration, unless explicitly set\n        if not isinstance(config.layout, str):\n            config.layout = self.config.listings_layout\n\n        # Inherit table of contents configuration, unless explicitly set\n        if not isinstance(config.toc, bool):\n            config.toc = self.config.listings_toc\n\n        # Return listing configuration\n        return config","sourceCodeStart":356,"sourceCodeEnd":392,"githubUrl":"https://github.com/squidfunk/mkdocs-material/blob/e2136532f40aed98af1f6497c0cc6a3cff9f759b/src/plugins/tags/structure/listing/manager/__init__.py#L356-L392","documentation":"`_resolve` loads a listing configuration from a YAML file and validates it; parse/validation failures (and warnings) are collected, and the first error is re-raised as this PluginError with the file's relative path and the underlying error message, aborting resolution.","triggerScenarios":"A listing YAML file referenced from the tags plugin config contains invalid YAML or fails schema validation (e.g. non-dictionary root, unknown/invalid keys like a malformed `scope` or `tags` value); the path is wrong so loading itself fails.","commonSituations":"Sharing listing configs across projects with tabs-vs-spaces YAML errors; editing the YAML and introducing a bad key; referencing an external listings file that moved; schema changes between mkdocs-material versions.","solutions":["Open the YAML file named in the error and fix the specific problem listed after the newline (syntax or validation error).","Validate the file with `yaml.safe_load(open(path))` and compare its keys against the tags plugin listing schema (`listing`, `scope`, `tags`, etc.).","Correct the file path in the plugin's `listings` config if loading failed.","Bump/align mkdocs-material version if the schema key was renamed in your installed release."],"exampleFix":"# before listings.yml\ntaggings:\n  scope: ...\n\n# after\nlisting:\n  scope: ...\n","handlingStrategy":"validation","validationCode":"import yaml\nfor path in listing_paths:\n    with open(path) as f:\n        doc = yaml.safe_load(f)\n    assert isinstance(doc, dict), f\"{path}: listing config must be a mapping\"\n    assert set(doc) <= {'listing', 'scope', 'tags', ...}, f\"{path}: unknown keys {set(doc)}\"","typeGuard":"def is_valid_listing_doc(doc):\n    return isinstance(doc, dict) and isinstance(doc.get('listing', {}), dict)","tryCatchPattern":"from mkdocs.exceptions import PluginError\ntry:\n    manager.replace(...)\nexcept PluginError as e:\n    log.error(f\"Listing YAML problem: {e}\")\n    raise SystemExit(1)","preventionTips":["Lint listing YAML files with yamllint before committing","Keep listing files' schema in sync with your mkdocs-material version","Reference listings via stable relative paths checked into the repo"],"tags":["mkdocs-material","tags-plugin","yaml","configuration","schema-validation-failed"],"backgroundTag":"invalid-config-file","analyzedSha":"e2136532f40aed98af1f6497c0cc6a3cff9f759b","analyzedAt":"2026-08-29T11:20:04.299Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}