BabylonJS/Babylon.js · error

Invalid JSON format. Please check documentation for format s

Error message

Invalid JSON format. Please check documentation for format specifications.

What it means

SpriteManager.load() fetches a spritemap JSON from a URL and parses it inside its onload handler. If parsing fails or the fetched document does not match the documented spritemap format (no usable frames), the manager disables packed mode and throws this error. It tells the developer the loaded JSON is unusable as a packed spritesheet descriptor.

Source

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

                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);
                    this._spriteMap = spritemap;
                    this._packedAndReady = true;
                    this._cellData = celldata.frames;
                } catch (e) {
                    this._fromPacked = false;
                    this._packedAndReady = false;
                    throw new Error("Invalid JSON format. Please check documentation for format specifications.", { cause: e });
                }
            };
            Tools.LoadFile(jsonUrl, onload, undefined, undefined, false, onerror);
        }
    }

    private _checkTextureAlpha(sprite: Sprite, ray: Ray, distance: number, min: Vector3, max: Vector3) {
        if (!sprite.useAlphaForPicking || !this.texture?.isReady()) {
            return true;
        }

        const textureSize = this.texture.getSize();
        if (!this._textureContent) {
            this._textureContent = new Uint8Array(textureSize.width * textureSize.height * 4);
            // eslint-disable-next-line @typescript-eslint/no-floating-promises
            this.texture.readPixels(0, 0, this._textureContent);
        }

View on GitHub (pinned to 0592b347b8)

Solutions

1. Open jsonUrl directly in a browser or curl it and confirm it returns valid JSON with a frames object
2. Check the network tab for the actual status code/content-type of the request (404/500 bodies often fail JSON.parse)
3. Re-export the spritesheet in the documented format and redeploy it
4. Wrap load() in try/catch and inspect e.cause for the JSON.parse failure details

Example fix

// before
spriteManager.load('/assets/sheet.json');
// after
fetch('/assets/sheet.json')
  .then(r => {
    if (!r.ok) throw new Error(`HTTP ${r.status}`);
    return r.json();
  })
  .then(json => {
    if (!json.frames) throw new Error('missing frames');
  })
  .then(() => spriteManager.load('/assets/sheet.json'))
  .catch(e => console.error('spritemap load failed', e));

const res = await fetch(jsonUrl);
if (!res.ok) throw new Error(`spritemap fetch failed: ${res.status}`);
const json = await res.json();
if (!json || !json.frames) throw new Error('spritemap missing frames');

function looksLikeSpritemap(v: unknown): boolean {
  return typeof v === 'object' && v !== null && 'frames' in (v as object);
}

try {
  spriteManager.load(jsonUrl);
} catch (e) {
  console.error('spritemap load failed:', (e as Error).cause);
  // fall back to a fixed cell-size sprite manager
}

When it happens

Trigger: Calling spriteManager.load(jsonUrl) where the URL returns malformed JSON, an HTML error page, a 404 body, or JSON missing the documented frames/animation structure; also when the loaded data does not contain .frames for cell data.

Common situations: Wrong URL path or CORS response returning an error page, server replying with text/html content type for a missing file, atlas exported in an unsupported format, cached stale JSON that no longer matches the texture.

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. Check the frame values and make sure t
• Nothing else parsed so far
• Unable to load the snippet ${snippetId}
• Failed to fetch image "${url}": ${response.status} ${respons

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