{"record":{"id":"8b1745a23f607109","repo":"BabylonJS/Babylon.js","slug":"failed-to-create-imagebitmap","errorCode":null,"errorMessage":"Failed to create ImageBitmap","messagePattern":"Failed to create ImageBitmap","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/dev/loaders/src/SPLAT/sog.pure.ts","lineNumber":103,"sourceCode":"    /**\r\n     * number of splats (optional, can be inferred from means.shape[0])\r\n     */\r\n    count?: number;\r\n}\r\n\r\n// eslint-disable-next-line @typescript-eslint/naming-convention\r\ninterface IWebPImage {\r\n    bits: Uint8Array;\r\n    width: number;\r\n    height: number;\r\n}\r\nconst SH_C0 = 0.28209479177387814;\r\n\r\nasync function LoadWebpImageData(rootUrlOrData: string | Uint8Array, filename: string, engine: AbstractEngine): Promise<IWebPImage> {\r\n    const promise = new Promise<IWebPImage>((resolve, reject) => {\r\n        const image = engine.createCanvasImage();\r\n        if (!image) {\r\n            throw new Error(\"Failed to create ImageBitmap\");\r\n        }\r\n        image.onload = () => {\r\n            try {\r\n                // Draw to canvas\r\n                const canvas = engine.createCanvas(image.width, image.height);\r\n                if (!canvas) {\r\n                    throw new Error(\"Failed to create canvas\");\r\n                }\r\n                const ctx = canvas.getContext(\"2d\");\r\n                if (!ctx) {\r\n                    throw new Error(\"Failed to get 2D context\");\r\n                }\r\n                ctx.drawImage(image, 0, 0);\r\n\r\n                // Extract pixel data (RGBA per pixel)\r\n                const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);\r\n                resolve({ bits: new Uint8Array(imageData.data.buffer), width: imageData.width, height: imageData.height });\r\n            } catch (error) {\r","sourceCodeStart":85,"sourceCodeEnd":121,"githubUrl":"https://github.com/BabylonJS/Babylon.js/blob/0592b347b8a4ee0236089ea86a749cacfdb266d8/packages/dev/loaders/src/SPLAT/sog.pure.ts#L85-L121","documentation":"LoadWebpImageData decodes SOG (Self-Organizing Gaussians) WebP image payloads by creating an image via engine.createCanvasImage(). If the engine cannot create a canvas image element (returns null/undefined), decoding cannot proceed and this error is thrown synchronously inside the promise executor. It indicates the rendering environment lacks canvas/image support.","triggerScenarios":"Loading a .sog file on an engine/context where createCanvasImage() returns null — e.g. headless/Node environment without a canvas implementation, or an engine that doesn't support 2D canvas image creation.","commonSituations":"Running the loader server-side (SSR/tests) without node-canvas polyfill; OffscreenCanvas-disabled environments; engines created before a valid canvas backend is available.","solutions":["Ensure loading happens in a browser-like environment with canvas support; polyfill with node-canvas for Node.","Verify the engine is properly initialized with a real canvas before loading SOG assets.","Check that createCanvasImage is supported by your engine subclass; fall back to a DOM Image/ImageBitmap path if available.","Since the throw occurs inside a Promise executor, catch the async rejection rather than relying on synchronous throw semantics."],"exampleFix":"// before\n// Node.js, no canvas: engine.createCanvasImage() -> null, error thrown\n// after\nimport { installCanvasPolyfill } from \"@loaders.gl/polyfills\"; // or node-canvas shim\ninstallCanvasPolyfill();\nawait loadSogAsync(url, engine);","handlingStrategy":"fallback","validationCode":"const image = engine.createCanvasImage?.();\nif (!image) {\n  throw new Error(\"Environment cannot create canvas images; SOG WebP decoding unavailable\");\n}","typeGuard":"function supportsCanvasImage(engine: AbstractEngine): boolean {\n  return typeof (engine as any).createCanvasImage === \"function\" && !!engine.createCanvasImage();\n}","tryCatchPattern":"try {\n  const img = await loadMeansImageAsync(url, engine);\n} catch (e) {\n  if (String(e.message).includes(\"Failed to create ImageBitmap\")) {\n    // fallback: decode via createImageBitmap or an external decoder\n    const blob = await fetch(url).then(r => r.blob());\n    const bitmap = await createImageBitmap(blob);\n  } else throw e;\n}","preventionTips":["Run SOG loading in a canvas-capable environment (browser, or polyfilled Node).","Initialize the engine against a real canvas before loading assets.","Feature-detect createCanvasImage in tests/SSR and provide a decoder fallback.","Note the throw occurs in a promise executor — always await and catch the rejection."],"tags":["splat","sog","canvas","environment","webp"],"backgroundTag":"canvas-not-supported","analyzedSha":"0592b347b8a4ee0236089ea86a749cacfdb266d8","analyzedAt":"2026-08-30T15:11:20.442Z","schemaVersion":2},"datasetVersion":"2026-08-30T18:17:15.746Z"}