{"record":{"id":"4aaf22797e3d928c","repo":"BabylonJS/Babylon.js","slug":"invalid-json-format-please-check-documentation-fo","errorCode":null,"errorMessage":"Invalid JSON format. Please check documentation for format specifications.","messagePattern":"Invalid JSON format\\. Please check documentation for format specifications\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/dev/core/src/Sprites/spriteManager.ts","lineNumber":446,"sourceCode":"                re.test(imgUrl);\r\n            } while (re.lastIndex > 0);\r\n            const jsonUrl = imgUrl.substring(0, li - 1) + \".json\";\r\n            const onerror = () => {\r\n                Logger.Error(\"JSON ERROR: Unable to load JSON file.\");\r\n                this._fromPacked = false;\r\n                this._packedAndReady = false;\r\n            };\r\n            const onload = (data: string | ArrayBuffer) => {\r\n                try {\r\n                    const celldata = JSON.parse(data as string);\r\n                    const spritemap = <string[]>Reflect.ownKeys(celldata.frames);\r\n                    this._spriteMap = spritemap;\r\n                    this._packedAndReady = true;\r\n                    this._cellData = celldata.frames;\r\n                } catch (e) {\r\n                    this._fromPacked = false;\r\n                    this._packedAndReady = false;\r\n                    throw new Error(\"Invalid JSON format. Please check documentation for format specifications.\", { cause: e });\r\n                }\r\n            };\r\n            Tools.LoadFile(jsonUrl, onload, undefined, undefined, false, onerror);\r\n        }\r\n    }\r\n\r\n    private _checkTextureAlpha(sprite: Sprite, ray: Ray, distance: number, min: Vector3, max: Vector3) {\r\n        if (!sprite.useAlphaForPicking || !this.texture?.isReady()) {\r\n            return true;\r\n        }\r\n\r\n        const textureSize = this.texture.getSize();\r\n        if (!this._textureContent) {\r\n            this._textureContent = new Uint8Array(textureSize.width * textureSize.height * 4);\r\n            // eslint-disable-next-line @typescript-eslint/no-floating-promises\r\n            this.texture.readPixels(0, 0, this._textureContent);\r\n        }\r\n\r","sourceCodeStart":428,"sourceCodeEnd":464,"githubUrl":"https://github.com/BabylonJS/Babylon.js/blob/0592b347b8a4ee0236089ea86a749cacfdb266d8/packages/dev/core/src/Sprites/spriteManager.ts#L428-L464","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Open jsonUrl directly in a browser or curl it and confirm it returns valid JSON with a frames object","Check the network tab for the actual status code/content-type of the request (404/500 bodies often fail JSON.parse)","Re-export the spritesheet in the documented format and redeploy it","Wrap load() in try/catch and inspect e.cause for the JSON.parse failure details"],"exampleFix":"// before\nspriteManager.load('/assets/sheet.json');\n// after\nfetch('/assets/sheet.json')\n  .then(r => {\n    if (!r.ok) throw new Error(`HTTP ${r.status}`);\n    return r.json();\n  })\n  .then(json => {\n    if (!json.frames) throw new Error('missing frames');\n  })\n  .then(() => spriteManager.load('/assets/sheet.json'))\n  .catch(e => console.error('spritemap load failed', e));","handlingStrategy":"try-catch","validationCode":"const res = await fetch(jsonUrl);\nif (!res.ok) throw new Error(`spritemap fetch failed: ${res.status}`);\nconst json = await res.json();\nif (!json || !json.frames) throw new Error('spritemap missing frames');","typeGuard":"function looksLikeSpritemap(v: unknown): boolean {\n  return typeof v === 'object' && v !== null && 'frames' in (v as object);\n}","tryCatchPattern":"try {\n  spriteManager.load(jsonUrl);\n} catch (e) {\n  console.error('spritemap load failed:', (e as Error).cause);\n  // fall back to a fixed cell-size sprite manager\n}","preventionTips":["Verify the URL returns 200 with content-type application/json","Validate the fetched document shape before/after loading","Bust stale caches when re-exporting atlases","Keep texture and spritemap versions in sync"],"tags":["json","spritesheet","network","parsing"],"backgroundTag":"invalid-json-atlas","analyzedSha":"0592b347b8a4ee0236089ea86a749cacfdb266d8","analyzedAt":"2026-08-30T15:11:20.442Z","schemaVersion":2},"datasetVersion":"2026-08-31T09:17:48.483Z"}