{"record":{"id":"bd7b0413d54b3d99","repo":"BabylonJS/Babylon.js","slug":"smartassetserializer-unsupported-asset-map-versio","errorCode":null,"errorMessage":"SmartAssetSerializer: Unsupported asset map version \"${doc.version}\". Expected version 1.","messagePattern":"SmartAssetSerializer: Unsupported asset map version \"(.+?)\"\\. Expected version 1\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/dev/core/src/SmartAssets/smartAssetSerializer.ts","lineNumber":49,"sourceCode":"    /** Map of asset keys to their serialized entries. */\n    readonly assets: Record<string, ISerializedSmartAssetEntry>;\n}\n\n/**\n * Validates and parses a serialized smart asset map document.\n * @param data - The raw data to validate (typically parsed JSON).\n * @returns The validated document.\n * @throws If the data does not conform to the expected schema.\n */\nexport function DeserializeSmartAssetMap(data: unknown): ISerializedSmartAssetMap {\n    if (!data || typeof data !== \"object\") {\n        throw new Error(\"SmartAssetSerializer: Invalid asset map — expected an object.\");\n    }\n\n    const doc = data as Record<string, unknown>;\n\n    if (doc.version !== 1) {\n        throw new Error(`SmartAssetSerializer: Unsupported asset map version \"${doc.version}\". Expected version 1.`);\n    }\n\n    if (!doc.assets || typeof doc.assets !== \"object\" || Array.isArray(doc.assets)) {\n        throw new Error(\"SmartAssetSerializer: Invalid asset map — 'assets' must be an object.\");\n    }\n\n    const assets = doc.assets as Record<string, unknown>;\n    for (const [key, entry] of Object.entries(assets)) {\n        if (!entry || typeof entry !== \"object\") {\n            throw new Error(`SmartAssetSerializer: Invalid entry for key \"${key}\" — expected an object.`);\n        }\n        const entryObj = entry as Record<string, unknown>;\n        if (typeof entryObj.url !== \"string\" || entryObj.url.length === 0) {\n            throw new Error(`SmartAssetSerializer: Invalid entry for key \"${key}\" — 'url' must be a non-empty string.`);\n        }\n    }\n\n    return data as ISerializedSmartAssetMap;","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/BabylonJS/Babylon.js/blob/0592b347b8a4ee0236089ea86a749cacfdb266d8/packages/dev/core/src/SmartAssets/smartAssetSerializer.ts#L31-L67","documentation":"After confirming the data is an object, DeserializeSmartAssetMap checks doc.version === 1. Any other value — missing version, version 2 from a newer app, a string \"1\", or 0/undefined from legacy or corrupt files — throws this error. The serializer only understands schema version 1 and refuses to guess at other layouts.","triggerScenarios":"Deserializing a project file written by a newer library version that bumped the version field; loading hand-authored JSON that omits \"version\"; comparing with == semantics expecting string \"1\" to pass; older backups whose root object lacked a version key.","commonSituations":"Opening a project saved by a colleague on a newer release; rolling back the app against newer project files; a manual edit that deleted the version field; JSON round-trips through tools that rewrote or dropped the version property.","solutions":["Open the file in an editor and set/add \"version\": 1 if the structure is otherwise valid version-1 format.","Upgrade the library/app to the version that wrote the file, then re-export/migrate it down to version 1.","Write a migration step that converts higher-version maps to version 1 before calling DeserializeSmartAssetMap.","Validate the version field at file-ingest time and surface a clear 'please upgrade' message to users.","Check for a type mismatch: the field must be the number 1, not the string \"1\"."],"exampleFix":"// before\nconst doc = DeserializeSmartAssetMap(parsed); // parsed.version === \"1\"\n// after\nif (typeof parsed.version === \"string\") {\n    parsed.version = Number(parsed.version);\n}\nif (parsed.version > 1) {\n    parsed = migrateToV1(parsed); // downgrade newer schemas first\n}\nconst doc = DeserializeSmartAssetMap(parsed);","handlingStrategy":"validation","validationCode":"function hasSupportedVersion(data: unknown): data is { version: 1; assets: object } {\n    return (\n        typeof data === \"object\" && data !== null &&\n        (data as { version?: unknown }).version === 1 &&\n        typeof (data as { assets?: unknown }).assets === \"object\"\n    );\n}\n// call site:\nif (!hasSupportedVersion(parsed)) {\n    // migrate or reject before deserializing\n}\nconst doc = DeserializeSmartAssetMap(parsed);","typeGuard":"function isVersion1AssetMap(data: unknown): data is { version: 1; assets: Record<string, unknown> } {\n    return (\n        typeof data === \"object\" && data !== null &&\n        (data as { version?: unknown }).version === 1 &&\n        typeof (data as { assets?: unknown }).assets === \"object\" &&\n        (data as { assets?: unknown }).assets !== null &&\n        !Array.isArray((data as { assets?: unknown }).assets)\n    );\n}","tryCatchPattern":"let doc: ISerializedSmartAssetMap;\ntry {\n    doc = DeserializeSmartAssetMap(parsed);\n} catch (e) {\n    if (e instanceof Error && e.message.includes('Unsupported asset map version')) {\n        const v = (parsed as { version?: unknown }).version;\n        if (typeof v === 'number' && v > 1) {\n            doc = DeserializeSmartAssetMap(migrateToV1(parsed));\n        } else {\n            throw new Error(`Project file version ${String(v)} is not supported — please upgrade the app.`, { cause: e });\n        }\n    } else {\n        throw e;\n    }\n}","preventionTips":["Check the version field numerically (=== 1) before deserializing user files.","Implement and register migration functions keyed by version for forward compatibility.","Reject string versions (\"1\") at ingest — the field must be the number 1.","Surface 'file saved by a newer version' errors with guidance instead of raw throws.","Never hand-edit the version field in project files without migrating the schema."],"tags":["serialization","schema-validation","version-mismatch","smart-assets"],"backgroundTag":"unsupported-schema-version","analyzedSha":"0592b347b8a4ee0236089ea86a749cacfdb266d8","analyzedAt":"2026-08-30T15:11:20.442Z","schemaVersion":2},"datasetVersion":"2026-08-30T18:17:15.746Z"}