{"record":{"id":"eba0089f11af7408","repo":"BabylonJS/Babylon.js","slug":"projectfile-invalid-project-file-overrides-mu","errorCode":null,"errorMessage":"ProjectFile: Invalid project file — 'overrides' must be an array.","messagePattern":"ProjectFile: Invalid project file — 'overrides' must be an array\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/dev/sharedUiComponents/src/projects/projectFile.ts","lineNumber":300,"sourceCode":" * @throws If the data does not conform to the expected schema.\r\n */\r\nexport function DeserializeProject(data: unknown): ISerializedProject {\r\n    if (!data || typeof data !== \"object\") {\r\n        throw new Error(\"ProjectFile: Invalid project file — expected an object.\");\r\n    }\r\n\r\n    const doc = data as Record<string, unknown>;\r\n\r\n    if (doc.version !== 2) {\r\n        throw new Error(`ProjectFile: Unsupported project version \"${doc.version}\". Expected version 2.`);\r\n    }\r\n\r\n    // Validate the asset map portion\r\n    DeserializeSmartAssetMap({ version: 1, assets: doc.assets });\r\n\r\n    // Validate overrides array\r\n    if (!Array.isArray(doc.overrides)) {\r\n        throw new Error(\"ProjectFile: Invalid project file — 'overrides' must be an array.\");\r\n    }\r\n\r\n    // Validate optional companion bindings (shape-only check)\r\n    if (doc.companionBindings !== undefined) {\r\n        if (typeof doc.companionBindings !== \"object\" || doc.companionBindings === null || Array.isArray(doc.companionBindings)) {\r\n            throw new Error(\"ProjectFile: Invalid project file — 'companionBindings' must be an object.\");\r\n        }\r\n    }\r\n\r\n    return data as ISerializedProject;\r\n}\r\n\r\n// ── Zip layer (.babylonproj on disk) ──\r\n\r\n/**\r\n * Serializes a scene's project (smart assets + overrides) into a `.babylonproj`\r\n * zip bundle.\r\n *\r","sourceCodeStart":282,"sourceCodeEnd":318,"githubUrl":"https://github.com/BabylonJS/Babylon.js/blob/0592b347b8a4ee0236089ea86a749cacfdb266d8/packages/dev/sharedUiComponents/src/projects/projectFile.ts#L282-L318","documentation":"After validating the version and asset map, DeserializeProject requires the top-level 'overrides' property to be an array. A missing, null, or non-array overrides value means the project file is malformed, so deserialization is aborted.","triggerScenarios":"Calling DeserializeProject on a document where doc.overrides is undefined, null, an object, or a string instead of an array.","commonSituations":"Hand-authoring project.json and forgetting the overrides array, a serializer bug omitting empty overrides, or JSON partial updates replacing the array with an object.","solutions":["Add an empty overrides array if the project has none: \"overrides\": [].","Fix the shape so overrides is a JSON array of override objects.","Verify the file was produced by a compatible exporter version that includes overrides.","Run the file through JSON schema validation before deserializing."],"exampleFix":"// before\n{ \"version\": 2, \"assets\": {}, \"overrides\": null }\n// after\n{ \"version\": 2, \"assets\": {}, \"overrides\": [] }","handlingStrategy":"validation","validationCode":"if (!Array.isArray(doc.overrides)) {\n    throw new Error('project file: overrides must be an array');\n}\nDeserializeProject(doc);","typeGuard":"function hasOverridesArray(data: unknown): data is { overrides: unknown[] } {\n    return typeof data === 'object' && data !== null && Array.isArray((data as any).overrides);\n}","tryCatchPattern":"try {\n    DeserializeProject(doc);\n} catch (e) {\n    if (e instanceof Error && e.message.includes(\"'overrides' must be an array\")) {\n        doc.overrides = [];\n        return DeserializeProject(doc);\n    }\n    throw e;\n}","preventionTips":["Always emit overrides: [] even when there are no overrides.","Validate project files against a JSON schema before deserializing.","Avoid partial JSON merges that can replace arrays with scalars or objects."],"tags":["deserialization","validation","json"],"backgroundTag":"schema-validation-failed","analyzedSha":"0592b347b8a4ee0236089ea86a749cacfdb266d8","analyzedAt":"2026-08-30T15:11:20.442Z","schemaVersion":2},"datasetVersion":"2026-08-30T18:17:15.746Z"}