BabylonJS/Babylon.js · error

createImageBitmapFromSource is not implemented

Error message

createImageBitmapFromSource is not implemented

What it means

AbstractEngine._createImageBitmapFromSource is an engine abstraction; the pure/base class intentionally throws 'not implemented' and only concrete engines (WebGL/WebGPU with proper host environment) override it. Hitting this means the code path ran on an engine that has no image-bitmap support, typically a headless/pure engine instance.

Source

Thrown at packages/dev/core/src/Engines/abstractEngine.pure.ts:2612

        return this._lockstepMaxSteps;
    }

    /**
     * Returns the time in ms between steps when using deterministic lock step.
     * @returns time step in (ms)
     */
    public getTimeStep(): number {
        return this._timeStep * 1000;
    }

    /**
     * Engine abstraction for loading and creating an image bitmap from a given source string.
     * @param imageSource source to load the image from.
     * @param options An object that sets options for the image's extraction.
     */
    // eslint-disable-next-line @typescript-eslint/promise-function-async
    public _createImageBitmapFromSource(imageSource: string, options?: ImageBitmapOptions): Promise<ImageBitmap> {
        throw new Error("createImageBitmapFromSource is not implemented");
    }

    /**
     * Engine abstraction for createImageBitmap
     * @param image source for image
     * @param options An object that sets options for the image's extraction.
     * @returns ImageBitmap
     */
    // eslint-disable-next-line @typescript-eslint/promise-function-async
    public createImageBitmap(image: ImageBitmapSource, options?: ImageBitmapOptions): Promise<ImageBitmap> {
        return createImageBitmap(image, options);
    }

    /**
     * Resize an image and returns the image data as an uint8array
     * @param image image to resize
     * @param bufferWidth destination buffer width
     * @param bufferHeight destination buffer height

View on GitHub (pinned to 0592b347b8)

Solutions

1. Run against a real engine (WebGL or WebGPU) in a browser supporting createImageBitmap
2. Provide an override/polyfill: monkey-patch engine._createImageBitmapFromSource to load via Image + decode and createImageBitmap
3. In Node, polyfill global createImageBitmap (e.g. via canvas/cimg) before engine use
4. Check engine._badOS/_features flags and choose a loader path not requiring ImageBitmap (options.imageBitmap false where supported)

Example fix

// before
const bmp = await engine._createImageBitmapFromSource(url); // throws on pure engine
// after
if (typeof engine._createImageBitmapFromSource !== 'function' || engine instanceof NullEngine) {
  const img = new Image(); img.src = url; await img.decode();
  const bmp = await createImageBitmap(img, options);
} else {
  const bmp = await engine._createImageBitmapFromSource(url, options);
}

if (typeof createImageBitmap !== 'function' || engine instanceof NullEngine) {
  // use Image + decode fallback instead of engine._createImageBitmapFromSource
}

function supportsImageBitmap(engine: AbstractEngine): boolean {
  return typeof createImageBitmap === 'function' && !(engine as any).constructor.name.includes('Null');
}

try {
  bitmap = await engine._createImageBitmapFromSource(src, opts);
} catch (e) {
  if (e instanceof Error && e.message.includes('createImageBitmapFromSource is not implemented')) {
    const img = new Image(); img.src = src; await img.decode();
    bitmap = await createImageBitmap(img, opts);
  } else throw e;
}

When it happens

Trigger: Calling engine._createImageBitmapFromSource (directly or via loaders like KTX2/texture loading that use ImageBitmap) on an engine built without DOM/ImageBitmap support (e.g. NullEngine or a pure environment).

Common situations: Running Babylon in Node.js/worker without createImageBitmap polyfill; using NullEngine for tests while code path assumes a real engine; partial engine builds where the platform-specific layer was tree-shaken.

Related errors

• resizeImageBitmap is not implemented
• getFontOffset is not implemented
• You must implement this method
• No engine available
• All images must share the same dimensions. Image at index ${

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