BabylonJS/Babylon.js · error

Invalid JSON Format. Check the frame values and make sure t

Error message

Invalid JSON Format.  Check the frame values and make sure the name is the first parameter.

What it means

SpriteManager._makePacked parses packed-sprite atlas JSON where each frame entry is expected to be an object whose FIRST key is the frame name (a string). The code takes Object.keys(_f)[0] and treats it as the name; if the first key is not a string (e.g. a numeric index, meaning the frame was an array), it throws this error because the atlas JSON does not match the expected packed format.

Source

Thrown at packages/dev/core/src/Sprites/spriteManager.ts:404

    }

    private _makePacked(imgUrl: string, spriteJSON: any) {
        if (spriteJSON !== null) {
            try {
                //Get the JSON and Check its structure.  If its an array parse it if its a JSON string etc...
                let celldata: any;
                if (typeof spriteJSON === "string") {
                    celldata = JSON.parse(spriteJSON);
                } else {
                    celldata = spriteJSON;
                }

                if (celldata.frames.length) {
                    const frametemp: any = {};
                    for (let i = 0; i < celldata.frames.length; i++) {
                        const _f = celldata.frames[i];
                        if (typeof Object.keys(_f)[0] !== "string") {
                            throw new Error("Invalid JSON Format.  Check the frame values and make sure the name is the first parameter.");
                        }

                        const name: string = _f[Object.keys(_f)[0]];
                        frametemp[name] = _f;
                    }
                    celldata.frames = frametemp;
                }

                const spritemap = <string[]>Reflect.ownKeys(celldata.frames);

                this._spriteMap = spritemap;
                this._packedAndReady = true;
                this._cellData = celldata.frames;
            } catch (e) {
                this._fromPacked = false;
                this._packedAndReady = false;
                throw new Error("Invalid JSON from string. Spritesheet managed with constant cell size.", { cause: e });
            }

View on GitHub (pinned to 0592b347b8)

Solutions

1. Check the atlas JSON: each entry in celldata.frames must be an object whose first key is the frame name string; re-export with the correct packer preset/format.
2. If your frames are arrays or use a different schema, transform them before constructing SpriteManager (map to {name: frameData} objects).
3. Verify you are feeding packed-atlas JSON to _makePacked, not plain sprite-sheet data — use the appropriate manager/path for that format.
4. Validate the JSON against a known-good working atlas file from the same tool version to spot structural drift.

Example fix

// before (array entries -> numeric first key)
"frames": [ ["walk_0", {x:0,y:0}], ["walk_1", {x:32,y:0}] ]

// after (name-keyed objects)
"frames": [
  { "walk_0": { x: 0, y: 0, w: 32, h: 32 } },
  { "walk_1": { x: 32, y: 0, w: 32, h: 32 } }
]

function isValidPackedFrames(json) {
  const frames = json?.celldata?.frames;
  if (!Array.isArray(frames)) return false;
  return frames.every(f =>
    f && typeof f === "object" && !Array.isArray(f) &&
    typeof Object.keys(f)[0] === "string"
  );
}
if (!isValidPackedFrames(atlasJson)) throw new Error("Atlas JSON is not in expected packed format");

function isNamedFrame(f: unknown): f is Record<string, object> & { firstKeyName: string } {
  if (typeof f !== "object" || f === null || Array.isArray(f)) return false;
  const first = Object.keys(f)[0];
  return typeof first === "string" && typeof (f as Record<string, unknown>)[first] === "object";
}

let spriteManager;
try {
  spriteManager = new SpriteManager(atlasJson, ...);
} catch (e) {
  if (e.message.startsWith("Invalid JSON Format")) {
    console.error("Atlas frames are not name-keyed objects; re-export with the correct packer preset.", atlasJson.frames?.[0]);
  } else throw e;
}

When it happens

Trigger: Constructing a SpriteManager (constructor -> _makePacked) with atlas JSON where celldata.frames is an array whose elements are not name-keyed objects — e.g. frames entries are arrays, or the frames object/array structure was produced by a different exporter format so Object.keys(_f)[0] is a numeric index ("0", or a non-string key).

Common situations: Using an atlas exported by a third-party packer (TexturePacker variants, custom scripts) whose frame layout differs from the expected {"frameName": {...}} per entry; passing sprite-sheet JSON instead of packed-atlas JSON; a version change in the export tool that wrapped frames differently; forgetting to run the tool's own converter step.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Invalid JSON from string. Spritesheet managed with constant
• Invalid JSON format. Please check documentation for format s
• Nothing else parsed so far
• SmartAssetSerializer: Invalid asset map — 'assets' must be a
• SmartAssetSerializer: Invalid entry for key "${key}" — expec

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