ProjectFile: Invalid project file — 'overrides' must be an a

Error message

ProjectFile: Invalid project file — 'overrides' must be an array.

What it means

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.

Source

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

 * @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;
}

// ── Zip layer (.babylonproj on disk) ──

/**
 * Serializes a scene's project (smart assets + overrides) into a `.babylonproj`
 * zip bundle.
 *

View on GitHub (pinned to 0592b347b8)

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.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

if (!Array.isArray(doc.overrides)) {
    throw new Error('project file: overrides must be an array');
}
DeserializeProject(doc);

Type guard

function hasOverridesArray(data: unknown): data is { overrides: unknown[] } {
    return typeof data === 'object' && data !== null && Array.isArray((data as any).overrides);
}

Try / catch

try {
    DeserializeProject(doc);
} catch (e) {
    if (e instanceof Error && e.message.includes("'overrides' must be an array")) {
        doc.overrides = [];
        return DeserializeProject(doc);
    }
    throw e;
}

Prevention

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.

When it happens

Trigger: Calling DeserializeProject on a document where doc.overrides is undefined, null, an object, or a string instead of an array.

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

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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