{"record":{"id":"69e73a83100a91b8","repo":"BabylonJS/Babylon.js","slug":"projectfile-unsupported-project-version-doc-ve","errorCode":null,"errorMessage":"ProjectFile: Unsupported project version \"${doc.version}\". Expected version 2.","messagePattern":"ProjectFile: Unsupported project version \"(.+?)\"\\. Expected version 2\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/dev/sharedUiComponents/src/projects/projectFile.ts","lineNumber":292,"sourceCode":"        }\r\n    }\r\n}\r\n\r\n/**\r\n * Validates and parses a serialized project document.\r\n * @param data - The raw data to validate (typically parsed JSON).\r\n * @returns The validated project document.\r\n * @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","sourceCodeStart":274,"sourceCodeEnd":310,"githubUrl":"https://github.com/BabylonJS/Babylon.js/blob/0592b347b8a4ee0236089ea86a749cacfdb266d8/packages/dev/sharedUiComponents/src/projects/projectFile.ts#L274-L310","documentation":"DeserializeProject validates that a serialized project file declares version 2. Any document whose top-level 'version' property is missing or differs from the number 2 is rejected. This guards against loading project files written by older or newer incompatible versions of the tooling.","triggerScenarios":"Calling DeserializeProject with a JSON object whose doc.version is not strictly === 2 (e.g. version: 1, version: \"2\" as string, or version absent).","commonSituations":"Loading a hand-edited project.json, importing a project exported by an older tool version, stripping fields during a transform, or comparing with == instead of === in generated files.","solutions":["Re-export/save the project with the current tool so the file carries version: 2.","Edit the project file to set \"version\": 2 (numeric) if the content is otherwise compatible.","Check the file was not truncated or rewritten by a script that dropped the version field.","Add a migration step in your pipeline converting older serialized projects to version 2 before deserializing."],"exampleFix":"// before\n{ \"name\": \"myProject\", \"assets\": {} }\n// after\n{ \"version\": 2, \"name\": \"myProject\", \"assets\": {}, \"overrides\": [] }","handlingStrategy":"validation","validationCode":"function validateProjectDoc(data: unknown): boolean {\n    const doc = data as { version?: unknown };\n    return typeof data === 'object' && data !== null && doc.version === 2;\n}","typeGuard":"function isVersion2Project(data: unknown): data is { version: 2 } & Record<string, unknown> {\n    return typeof data === 'object' && data !== null && (data as any).version === 2;\n}","tryCatchPattern":"try {\n    const project = DeserializeProject(json);\n} catch (e) {\n    if (e instanceof Error && e.message.includes('Unsupported project version')) {\n        // migrate or re-export the project file\n    } else throw e;\n}","preventionTips":["Never hand-edit the version field of project files.","Pin exporter and consumer tool versions so schemas match.","Add a JSON schema check (version: { const: 2 }) in CI for project fixtures."],"tags":["deserialization","validation","versioning"],"backgroundTag":"unsupported-schema-version","analyzedSha":"0592b347b8a4ee0236089ea86a749cacfdb266d8","analyzedAt":"2026-08-30T15:11:20.442Z","schemaVersion":2},"datasetVersion":"2026-08-30T18:17:15.746Z"}