BabylonJS/Babylon.js · error

SmartAssetSerializer: Unsupported asset map version "${doc.v

Error message

SmartAssetSerializer: Unsupported asset map version "${doc.version}". Expected version 1.

What it means

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.

Source

Thrown at packages/dev/core/src/SmartAssets/smartAssetSerializer.ts:49

    /** Map of asset keys to their serialized entries. */
    readonly assets: Record<string, ISerializedSmartAssetEntry>;
}

/**
 * Validates and parses a serialized smart asset map document.
 * @param data - The raw data to validate (typically parsed JSON).
 * @returns The validated document.
 * @throws If the data does not conform to the expected schema.
 */
export function DeserializeSmartAssetMap(data: unknown): ISerializedSmartAssetMap {
    if (!data || typeof data !== "object") {
        throw new Error("SmartAssetSerializer: Invalid asset map — expected an object.");
    }

    const doc = data as Record<string, unknown>;

    if (doc.version !== 1) {
        throw new Error(`SmartAssetSerializer: Unsupported asset map version "${doc.version}". Expected version 1.`);
    }

    if (!doc.assets || typeof doc.assets !== "object" || Array.isArray(doc.assets)) {
        throw new Error("SmartAssetSerializer: Invalid asset map — 'assets' must be an object.");
    }

    const assets = doc.assets as Record<string, unknown>;
    for (const [key, entry] of Object.entries(assets)) {
        if (!entry || typeof entry !== "object") {
            throw new Error(`SmartAssetSerializer: Invalid entry for key "${key}" — expected an object.`);
        }
        const entryObj = entry as Record<string, unknown>;
        if (typeof entryObj.url !== "string" || entryObj.url.length === 0) {
            throw new Error(`SmartAssetSerializer: Invalid entry for key "${key}" — 'url' must be a non-empty string.`);
        }
    }

    return data as ISerializedSmartAssetMap;

View on GitHub (pinned to 0592b347b8)

Solutions

1. Open the file in an editor and set/add "version": 1 if the structure is otherwise valid version-1 format.
2. Upgrade the library/app to the version that wrote the file, then re-export/migrate it down to version 1.
3. Write a migration step that converts higher-version maps to version 1 before calling DeserializeSmartAssetMap.
4. Validate the version field at file-ingest time and surface a clear 'please upgrade' message to users.
5. Check for a type mismatch: the field must be the number 1, not the string "1".

Example fix

// before
const doc = DeserializeSmartAssetMap(parsed); // parsed.version === "1"
// after
if (typeof parsed.version === "string") {
    parsed.version = Number(parsed.version);
}
if (parsed.version > 1) {
    parsed = migrateToV1(parsed); // downgrade newer schemas first
}
const doc = DeserializeSmartAssetMap(parsed);

function hasSupportedVersion(data: unknown): data is { version: 1; assets: object } {
    return (
        typeof data === "object" && data !== null &&
        (data as { version?: unknown }).version === 1 &&
        typeof (data as { assets?: unknown }).assets === "object"
    );
}
// call site:
if (!hasSupportedVersion(parsed)) {
    // migrate or reject before deserializing
}
const doc = DeserializeSmartAssetMap(parsed);

function isVersion1AssetMap(data: unknown): data is { version: 1; assets: Record<string, unknown> } {
    return (
        typeof data === "object" && data !== null &&
        (data as { version?: unknown }).version === 1 &&
        typeof (data as { assets?: unknown }).assets === "object" &&
        (data as { assets?: unknown }).assets !== null &&
        !Array.isArray((data as { assets?: unknown }).assets)
    );
}

let doc: ISerializedSmartAssetMap;
try {
    doc = DeserializeSmartAssetMap(parsed);
} catch (e) {
    if (e instanceof Error && e.message.includes('Unsupported asset map version')) {
        const v = (parsed as { version?: unknown }).version;
        if (typeof v === 'number' && v > 1) {
            doc = DeserializeSmartAssetMap(migrateToV1(parsed));
        } else {
            throw new Error(`Project file version ${String(v)} is not supported — please upgrade the app.`, { cause: e });
        }
    } else {
        throw e;
    }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• SmartAssetSerializer: Invalid asset map — expected an object
• Unknown vector class name ${className}
• Could not find signal input with name ${name} in block ${cla
• Could not find signal output with name ${name} in block ${cl
• GaussianSplattingPartProxyMesh: compound mesh not found with

AI-assisted analysis of BabylonJS/Babylon.js@0592b347b8 (2026-08-30). Data as JSON: /api/errors/bd7b0413d54b3d99. Report an issue: GitHub.