BabylonJS/Babylon.js · error

ProjectFile: Unsupported project version "${doc.version}". E

Error message

ProjectFile: Unsupported project version "${doc.version}". Expected version 2.

What it means

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.

Source

Thrown at packages/dev/sharedUiComponents/src/projects/projectFile.ts:292

        }
    }
}

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

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

    if (doc.version !== 2) {
        throw new Error(`ProjectFile: Unsupported project version "${doc.version}". Expected version 2.`);
    }

    // Validate the asset map portion
    DeserializeSmartAssetMap({ version: 1, assets: doc.assets });

    // Validate overrides array
    if (!Array.isArray(doc.overrides)) {
        throw new Error("ProjectFile: Invalid project file — 'overrides' must be an array.");
    }

    // Validate optional companion bindings (shape-only check)
    if (doc.companionBindings !== undefined) {
        if (typeof doc.companionBindings !== "object" || doc.companionBindings === null || Array.isArray(doc.companionBindings)) {
            throw new Error("ProjectFile: Invalid project file — 'companionBindings' must be an object.");
        }
    }

    return data as ISerializedProject;

View on GitHub (pinned to 0592b347b8)

Solutions

1. Re-export/save the project with the current tool so the file carries version: 2.
2. Edit the project file to set "version": 2 (numeric) if the content is otherwise compatible.
3. Check the file was not truncated or rewritten by a script that dropped the version field.
4. Add a migration step in your pipeline converting older serialized projects to version 2 before deserializing.

Example fix

// before
{ "name": "myProject", "assets": {} }
// after
{ "version": 2, "name": "myProject", "assets": {}, "overrides": [] }

function validateProjectDoc(data: unknown): boolean {
    const doc = data as { version?: unknown };
    return typeof data === 'object' && data !== null && doc.version === 2;
}

function isVersion2Project(data: unknown): data is { version: 2 } & Record<string, unknown> {
    return typeof data === 'object' && data !== null && (data as any).version === 2;
}

try {
    const project = DeserializeProject(json);
} catch (e) {
    if (e instanceof Error && e.message.includes('Unsupported project version')) {
        // migrate or re-export the project file
    } else throw e;
}

When it happens

Trigger: Calling DeserializeProject with a JSON object whose doc.version is not strictly === 2 (e.g. version: 1, version: "2" as string, or version absent).

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

Related errors

• SmartAssetSerializer: Invalid asset map — 'assets' must be a
• SmartAssetSerializer: Invalid entry for key "${key}" — expec
• SmartAssetSerializer: Invalid entry for key "${key}" — 'url'
• OverrideManager: Expected an array of override entries.
• ProjectFile: Invalid project file — expected an object.

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