BabylonJS/Babylon.js · error

Failed to create ImageBitmap

Error message

Failed to create ImageBitmap

What it means

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.

Source

Thrown at packages/dev/loaders/src/SPLAT/sog.pure.ts:103

    /**
     * number of splats (optional, can be inferred from means.shape[0])
     */
    count?: number;
}

// eslint-disable-next-line @typescript-eslint/naming-convention
interface IWebPImage {
    bits: Uint8Array;
    width: number;
    height: number;
}
const SH_C0 = 0.28209479177387814;

async function LoadWebpImageData(rootUrlOrData: string | Uint8Array, filename: string, engine: AbstractEngine): Promise<IWebPImage> {
    const promise = new Promise<IWebPImage>((resolve, reject) => {
        const image = engine.createCanvasImage();
        if (!image) {
            throw new Error("Failed to create ImageBitmap");
        }
        image.onload = () => {
            try {
                // Draw to canvas
                const canvas = engine.createCanvas(image.width, image.height);
                if (!canvas) {
                    throw new Error("Failed to create canvas");
                }
                const ctx = canvas.getContext("2d");
                if (!ctx) {
                    throw new Error("Failed to get 2D context");
                }
                ctx.drawImage(image, 0, 0);

                // Extract pixel data (RGBA per pixel)
                const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
                resolve({ bits: new Uint8Array(imageData.data.buffer), width: imageData.width, height: imageData.height });
            } catch (error) {

View on GitHub (pinned to 0592b347b8)

Solutions

1. Ensure loading happens in a browser-like environment with canvas support; polyfill with node-canvas for Node.
2. Verify the engine is properly initialized with a real canvas before loading SOG assets.
3. Check that createCanvasImage is supported by your engine subclass; fall back to a DOM Image/ImageBitmap path if available.
4. Since the throw occurs inside a Promise executor, catch the async rejection rather than relying on synchronous throw semantics.

Example fix

// before
// Node.js, no canvas: engine.createCanvasImage() -> null, error thrown
// after
import { installCanvasPolyfill } from "@loaders.gl/polyfills"; // or node-canvas shim
installCanvasPolyfill();
await loadSogAsync(url, engine);

const image = engine.createCanvasImage?.();
if (!image) {
  throw new Error("Environment cannot create canvas images; SOG WebP decoding unavailable");
}

function supportsCanvasImage(engine: AbstractEngine): boolean {
  return typeof (engine as any).createCanvasImage === "function" && !!engine.createCanvasImage();
}

try {
  const img = await loadMeansImageAsync(url, engine);
} catch (e) {
  if (String(e.message).includes("Failed to create ImageBitmap")) {
    // fallback: decode via createImageBitmap or an external decoder
    const blob = await fetch(url).then(r => r.blob());
    const bitmap = await createImageBitmap(blob);
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: Running the loader server-side (SSR/tests) without node-canvas polyfill; OffscreenCanvas-disabled environments; engines created before a valid canvas backend is available.

Related errors

• Failed to create canvas
• Failed to get 2D context
• filename is required when using a URL
• Missing arrays in SOG data.
• Failed to get client rect for rendering canvas

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