BabylonJS/Babylon.js · error

OverrideManager: Expected an array of override entries.

Error message

OverrideManager: Expected an array of override entries.

What it means

DeserializeAndApplyOverrides validates that the deserialized override payload is an array of IOverrideEntry before applying it to the scene's override registry. A non-array (null, object, string) means the project file's override section is corrupt or in an unexpected schema, so the function fails fast instead of iterating garbage.

Source

Thrown at packages/dev/sharedUiComponents/src/projects/overrideManager.ts:405

/**
 * Serializes all overrides to a JSON-compatible array.
 * The on-disk shape is identical to the in-memory `IOverrideEntry`.
 * @param scene - The scene whose overrides to serialize.
 * @returns An array of override entries (shallow copies).
 */
export function SerializeOverrides(scene: Scene): IOverrideEntry[] {
    const internal = GetOverrideInternals(GetOverrideManager(scene));
    return internal.overrides.map((o) => ({ ...o }));
}

/**
 * Loads overrides from a serialized array and applies them.
 * @param scene - The scene whose override registry to populate.
 * @param data - Array of override entries.
 */
export function DeserializeAndApplyOverrides(scene: Scene, data: IOverrideEntry[]): void {
    if (!Array.isArray(data)) {
        throw new Error("OverrideManager: Expected an array of override entries.");
    }

    for (const entry of SortNameOverridesFirst(data)) {
        if (!entry.targetType || entry.targetName === undefined || typeof entry.targetIndex !== "number" || !entry.propertyPath || entry.value === undefined) {
            Logger.Warn("OverrideManager: Skipping invalid override entry.");
            continue;
        }
        AddOverride(scene, entry);
    }
}

// ── Lifecycle ──

/**
 * Disposes the manager, clearing all overrides and detaching it from its scene.
 * Safe to call multiple times; subsequent calls are no-ops. Automatically invoked when the
 * owning scene is disposed.
 * @param manager - The override manager state.

View on GitHub (pinned to 0592b347b8)

Solutions

1. Fix the project file so overrides is an array of entries (version 2 schema).
2. Validate Array.isArray(parsed.overrides) after JSON.parse before calling the function.
3. If migrating from an older format, transform the old structure to the entry array first.
4. Check that the correct project file/version is being loaded (doc.version must be 2).

Example fix

// before
const data = JSON.parse(raw).overrides ?? {}; // object, not array
DeserializeAndApplyOverrides(scene, data); // throws
// after
const data = JSON.parse(raw).overrides;
if (Array.isArray(data)) DeserializeAndApplyOverrides(scene, data);

function isOverrideEntryArray(v) {
  return Array.isArray(v) && v.every((e) => e && typeof e === "object");
}
const data = parsed.overrides;
if (isOverrideEntryArray(data)) DeserializeAndApplyOverrides(scene, data);

function isOverrideEntryArray(v: unknown): v is IOverrideEntry[] {
  return Array.isArray(v) && v.every((e) => e !== null && typeof e === "object");
}

// try {
//   DeserializeAndApplyOverrides(scene, data);
// } catch (e) {
//   if (String(e.message).includes("Expected an array of override entries")) {
//     Logger.Warn("Project overrides missing/corrupt; skipping.");
//     return;
//   }
//   throw e;
// }

When it happens

Trigger: Calling DeserializeAndApplyOverrides(scene, data) where data is null, undefined, a plain object, or a string — typically because project JSON stored overrides under a different shape or a stale/other version of the schema.

Common situations: Loading a project file written by an older/newer version where overrides was an object map instead of an array; hand-edited JSON that wrapped the array in another key; failed fetch returning an error object passed straight to the deserializer.

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

• ProjectFile: Invalid project file — expected an object.
• SmartAssetSerializer: Invalid asset map — 'assets' must be a
• SmartAssetSerializer: Invalid entry for key "${key}" — expec
• SmartAssetSerializer: Invalid entry for key "${key}" — 'url'
• ProjectFile: Unsupported project version "${doc.version}". E

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