{"record":{"id":"a8ca729a7f1d4664","repo":"squidfunk/mkdocs-material","slug":"expected-list-but-received-mappings","errorCode":null,"errorMessage":"Expected list, but received: {mappings}","messagePattern":"Expected list, but received: (.+?)","errorType":"validation","errorClass":"ValidationError","httpStatus":null,"severity":"error","filePath":"src/plugins/tags/structure/mapping/storage/__init__.py","lineNumber":102,"sourceCode":"        Arguments:\n            path: The file path.\n\n        Yields:\n            The current mapping.\n        \"\"\"\n        with open(path, \"r\", encoding = \"utf-8\") as f:\n            data = json.load(f)\n\n            # Ensure root dictionary\n            if not isinstance(data, dict):\n                raise ValidationError(\n                    f\"Expected dictionary, but received: {data}\"\n                )\n\n            # Ensure mappings are iterable\n            mappings = data.get(\"mappings\")\n            if not isinstance(mappings, list):\n                raise ValidationError(\n                    f\"Expected list, but received: {mappings}\"\n                )\n\n            # Create and yield mappings\n            for mapping in mappings:\n                yield _mapping_from_json(mapping)\n\n# -----------------------------------------------------------------------------\n# Functions\n# -----------------------------------------------------------------------------\n\ndef _mapping_to_json(mapping: Mapping) -> dict:\n    \"\"\"\n    Return a serializable representation of a mapping.\n\n    Arguments:\n        mapping: The mapping.\n","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/squidfunk/mkdocs-material/blob/e2136532f40aed98af1f6497c0cc6a3cff9f759b/src/plugins/tags/structure/mapping/storage/__init__.py#L84-L120","documentation":"After confirming the root of a serialized mappings file is a dictionary, `Storage.load` fetches the `mappings` key and requires it to be a JSON list to iterate and deserialize each entry. A missing or non-list `mappings` value raises this ValidationError.","triggerScenarios":"Mapping JSON where `mappings` is absent, an object/dict, a string, or null; hand-crafted cache files; format drift from a different plugin version that stored mappings as a dict keyed by tag.","commonSituations":"Editing exports and replacing the array with an object; mixing files produced by incompatible mkdocs-material versions; partial writes/truncation corrupting the structure.","solutions":["Ensure the file contains a top-level `\"mappings\": [ ... ]` array of mapping objects.","Regenerate the file using the export tooling of the installed mkdocs-material version.","If migrating from an older format, convert the keyed dict of mappings into an array.","Guard the load site by checking `isinstance(data.get('mappings'), list)` first."],"exampleFix":"// before\n{\n  \"mappings\": {\"tag-a\": [...]}\n}\n\n// after\n{\n  \"mappings\": [\n    {\"tags\": [\"tag-a\"], ...}\n  ]\n}","handlingStrategy":"type-guard","validationCode":"import json\nwith open(path) as f:\n    data = json.load(f)\nassert isinstance(data, dict) and isinstance(data.get('mappings'), list), f\"{path}: expected {'mappings': [...] }\"","typeGuard":"def has_valid_mappings(data):\n    m = data.get('mappings') if isinstance(data, dict) else None\n    return isinstance(m, list)","tryCatchPattern":"try:\n    yield from storage.load(path)\nexcept ValidationError as e:\n    log.error(f\"Bad 'mappings' key in {path}: {e}\")\n    raise SystemExit(1)","preventionTips":["Generate mappings files only via the plugin's export feature","Keep producer and consumer on the same mkdocs-material version","Validate `mappings` is an array before load"],"tags":["json","validation","tags-plugin","mkdocs-material"],"backgroundTag":"schema-validation-failed","analyzedSha":"e2136532f40aed98af1f6497c0cc6a3cff9f759b","analyzedAt":"2026-08-29T11:20:04.299Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}