Invalid JSON from string. Spritesheet managed with constant

Error message

Invalid JSON from string. Spritesheet managed with constant cell size.

What it means

In SpriteManager's packed mode (_makePacked), the constructor parses a JSON string describing the spritesheet's frames/cells. If JSON.parse fails or the parsed object does not have the expected shape (e.g. no frames array), the manager flags itself as unpacked and throws this error so the caller knows the spritesheet falls back to constant-cell-size assumptions. The library throws because a malformed spritemap makes per-frame cell data unreliable.

Source

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

                        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 });
            }
        } else {
            const re = /\./g;
            let li: number;
            do {
                li = re.lastIndex;
                re.test(imgUrl);
            } while (re.lastIndex > 0);
            const jsonUrl = imgUrl.substring(0, li - 1) + ".json";
            const onerror = () => {
                Logger.Error("JSON ERROR: Unable to load JSON file.");
                this._fromPacked = false;
                this._packedAndReady = false;
            };
            const onload = (data: string | ArrayBuffer) => {
                try {
                    const celldata = JSON.parse(data as string);
                    const spritemap = <string[]>Reflect.ownKeys(celldata.frames);

View on GitHub (pinned to 0592b347b8)

Solutions

Validate the JSON string with JSON.parse and inspect the frames property before constructing the SpriteManager
Re-export the spritesheet using the format documented for packed SpriteManager input
Ensure you are passing the actual JSON content (not a URL) when using the packed string API
Log the underlying cause (e.cause) to see the exact JSON.parse syntax error

Example fix

// before
const sm = new SpriteManager(name, textureUrl, capacity, spriteJSONString);
// after
let parsed;
try {
  parsed = JSON.parse(spriteJSONString);
} catch (e) {
  parsed = null;
}
if (!parsed || !parsed.frames) {
  console.error('Spritesheet JSON malformed, using constant cell size');
}
const sm = new SpriteManager(name, textureUrl, capacity, spriteJSONString);

Defensive patterns

Strategy: validation

Validate before calling

function isValidPackedJson(s: string): boolean {
  try { const o = JSON.parse(s); return !!o && typeof o.frames !== 'undefined'; }
  catch { return false; }
}
if (!isValidPackedJson(spriteJSONString)) throw new Error('bad spritemap JSON');

Type guard

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

Try / catch

try {
  new SpriteManager(name, texUrl, capacity, spriteJSONString);
} catch (e) {
  console.error('spritemap JSON invalid:', (e as Error).cause);
  // fall back to constant cell size manager
}

Prevention

JSON.parse and inspect .frames before constructing the manager
Export atlases only in the documented format
Never pass an HTML error page body as the JSON string
Log e.cause to capture the precise JSON syntax problem

When it happens

Trigger: Calling new SpriteManager(...) with a packed spritemap JSON string that is syntactically invalid JSON, or valid JSON whose frames/animation data does not match the documented packed format (missing .frames).

Common situations: Hand-edited spritemap JSON, fetching the JSON with a tool that returned HTML/error pages instead of JSON, using an atlas exported from a tool with an unsupported format (e.g. non-TexturePacker layout), or trimming/encoding steps that corrupted the string before passing it to the manager.

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

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