{"record":{"id":"7c4c77eebb2839ac","repo":"abi/screenshot-to-code","slug":"design-systems-storage-must-contain-a-list","errorCode":null,"errorMessage":"Design systems storage must contain a list","messagePattern":"Design systems storage must contain a list","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"error","filePath":"backend/routes/design_systems.py","lineNumber":79,"sourceCode":"    except KeyError:\n        return None\n\n\ndef read_design_systems() -> list[DesignSystem]:\n    file_path = get_design_systems_file_path()\n    if not file_path.exists():\n        return []\n\n    try:\n        raw_items = cast(list[Any], json.loads(file_path.read_text(encoding=\"utf-8\")))\n    except json.JSONDecodeError as exc:\n        raise HTTPException(\n            status_code=500,\n            detail=\"Design systems storage is not valid JSON\",\n        ) from exc\n\n    if not isinstance(raw_items, list):\n        raise HTTPException(\n            status_code=500,\n            detail=\"Design systems storage must contain a list\",\n        )\n\n    design_systems: list[DesignSystem] = []\n    for raw_item in raw_items:\n        design_system = parse_design_system(raw_item)\n        if design_system:\n            design_systems.append(design_system)\n    return design_systems\n\n\ndef write_design_systems(design_systems: list[DesignSystem]) -> None:\n    file_path = get_design_systems_file_path()\n    file_path.parent.mkdir(parents=True, exist_ok=True)\n    tmp_path = file_path.with_suffix(\".json.tmp\")\n    serialized = json.dumps(\n        [design_system.model_dump() for design_system in design_systems],","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/abi/screenshot-to-code/blob/d026163f586dfa8c5c10d28c36edd59a9d3b0e88/backend/routes/design_systems.py#L61-L97","documentation":"Raised by read_design_systems() (500) when design-systems.json parses as valid JSON but the top-level value is not a list (e.g. an object like {\"items\": []}). The storage contract is a JSON array of design-system records; anything else is treated as structural corruption and fails every design-systems endpoint.","triggerScenarios":"Any /api/design-systems call after the file was replaced with a dict, a bare string, or a number — typically from a hand edit or an external tool writing a different schema.","commonSituations":"Users wrap the array in an object for 'readability'; migration scripts export a different shape; the file was overwritten by another application.","solutions":["Rewrite the file as a top-level JSON array of records: [{\"id\": ..., \"name\": ..., \"content\": ..., \"createdAt\": ..., \"updatedAt\": ...}, ...].","If you need the data, extract the inner list from the wrapper object and save it as the top level.","Reset with '[]' if the contents are disposable.","Verify with python -c \"import json;print(type(json.load(open(<path>))))\" -> should print <class 'list'>."],"exampleFix":"# before: {\"designSystems\": [{\"id\": \"1\", \"name\": \"DS\"}]}\nGET /api/design-systems  # 500\n\n# after: [{\"id\": \"1\", \"name\": \"DS\", \"content\": \"\", \"createdAt\": \"...\", \"updatedAt\": \"...\"}]","handlingStrategy":"validation","validationCode":"import json\n\ndef design_store_is_list(path: str) -> bool:\n    try:\n        return isinstance(json.loads(open(path, encoding=\"utf-8\").read()), list)\n    except (OSError, json.JSONDecodeError):\n        return False","typeGuard":"def is_design_store_shape(value: object) -> bool:\n    return isinstance(value, list)","tryCatchPattern":"try:\n    systems = requests.get(url + \"/api/design-systems\").raise_for_status().json()\nexcept requests.HTTPError as e:\n    if e.response is not None and \"must contain a list\" in e.response.text:\n        raise RuntimeError(\"storage schema wrong: top level must be a JSON array\") from e\n    raise","preventionTips":["Keep design-systems.json a top-level array of record objects.","If wrapping data, unwrap it back to an array before restarting the backend.","Automate backups so a schema mistake is recoverable."],"tags":["fastapi","http-500","json","schema","corruption","design-systems"],"backgroundTag":null,"analyzedSha":"d026163f586dfa8c5c10d28c36edd59a9d3b0e88","analyzedAt":"2026-08-14T22:02:06.951Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}