{"record":{"id":"8d69cbcc2ae1a27c","repo":"squidfunk/mkdocs-material","slug":"expected-dictionary-but-received-data","errorCode":null,"errorMessage":"Expected dictionary, but received: {data}","messagePattern":"Expected dictionary, but received: (.+?)","errorType":"validation","errorClass":"ValidationError","httpStatus":null,"severity":"error","filePath":"src/plugins/tags/structure/mapping/storage/__init__.py","lineNumber":95,"sourceCode":"            data = [_mapping_to_json(mapping) for mapping in mappings]\n            json.dump(dict(mappings = data), f)\n\n    def load(self, path: str) -> Iterable[Mapping]:\n        \"\"\"\n        Load mappings from file.\n\n        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","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/squidfunk/mkdocs-material/blob/e2136532f40aed98af1f6497c0cc6a3cff9f759b/src/plugins/tags/structure/mapping/storage/__init__.py#L77-L113","documentation":"`Storage.load` reads a serialized tags mapping JSON file and requires the top-level JSON value to be an object (dictionary) containing `mappings`. If `json.load` produced anything else (list, string, number, null), it raises this ValidationError.","triggerScenarios":"Loading a tags cache/exports file whose root is a JSON array or scalar; a truncated or hand-edited mapping file; passing the wrong file (e.g. an array export) to `load`.","commonSituations":"Manually merging or editing exported tags JSON and dropping the outer object; older/newer export formats with a different root shape; accidentally pointing the loader at a different JSON file.","solutions":["Ensure the JSON root is an object: `{\"mappings\": [...]}` — wrap the array if needed.","Re-export or regenerate the mappings file with the same mkdocs-material version rather than hand-editing it.","Verify the file path passed to `load` actually points to a mappings file, not another JSON artifact.","Add a pre-load check that the parsed JSON is a dict before calling `load`."],"exampleFix":"// before\n[\n  {\"tags\": [\"a\"], ...}\n]\n\n// after\n{\n  \"mappings\": [\n    {\"tags\": [\"a\"], ...}\n  ]\n}","handlingStrategy":"type-guard","validationCode":"import json\nwith open(path) as f:\n    data = json.load(f)\nif not isinstance(data, dict):\n    raise ValueError(f\"{path}: mappings file root must be a JSON object\")","typeGuard":"def is_mapping_file(data):\n    return isinstance(data, dict) and isinstance(data.get('mappings'), list)","tryCatchPattern":"from mkdocs.structure.files import ValidationError\ntry:\n    yield from storage.load(path)\nexcept ValidationError as e:\n    log.error(f\"Corrupt mappings file {path}: {e}\")\n    raise SystemExit(1)","preventionTips":["Never hand-edit exported mappings JSON; regenerate with the plugin's export tool","Check the root shape (object with `mappings` list) after any manual merge","Confirm the file path points at a mappings export, not another JSON artifact"],"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"}