What causes "Could not load a native texture." in BabylonJS/Babylon.js?

Verify the URL/buffer actually contains valid image bytes (log buffer length and magic bytes before createTexture).

Could not load a native texture.

Error message

Could not load a native texture.

What it means

After decoding image data, ThinNativeEngine hands the bytes to the native side and observes completion via a promise/callback pair; the rejection callback throws this error, meaning the native engine failed to upload/decode the texture into a bgfx-backed native texture.

Source

Thrown at packages/dev/core/src/Engines/thinNativeEngine.pure.ts:2072

                    () => {
                        texture.baseWidth = this._engine.getTextureWidth(underlyingResource);
                        texture.baseHeight = this._engine.getTextureHeight(underlyingResource);
                        texture.width = texture.baseWidth;
                        texture.height = texture.baseHeight;
                        texture.isReady = true;

                        const filter = getNativeSamplingMode(samplingMode);
                        this._setTextureSampling(underlyingResource, filter);

                        if (scene) {
                            scene.removePendingData(texture);
                        }

                        texture.onLoadedObservable.notifyObservers(texture);
                        texture.onLoadedObservable.clear();
                    },
                    () => {
                        throw new Error("Could not load a native texture.");
                    }
                );
            };

            if (fromData && buffer) {
                if (buffer instanceof ArrayBuffer) {
                    onload(new Uint8Array(buffer));
                } else if (ArrayBuffer.isView(buffer)) {
                    onload(buffer);
                } else if (typeof buffer === "string") {
                    onload(new Uint8Array(DecodeBase64UrlToBinary(buffer)));
                } else {
                    throw new Error("Unsupported buffer type");
                }
            } else {
                if (isBase64) {
                    onload(new Uint8Array(DecodeBase64UrlToBinary(url)));
                } else {

View on GitHub (pinned to 0592b347b8)

Solutions

Verify the URL/buffer actually contains valid image bytes (log buffer length and magic bytes before createTexture).
Convert the asset to a widely supported format (PNG/JPG) and retry.
Ensure the NativeEngine runtime includes the needed image codecs (e.g. basis/astc support) for your target platform.

Example fix

// before
const tex = engine.createTexture(resp.url, false, () => {}, () => {}); // url served 404 HTML

// after
const res = await fetch(resp.url);
if (!res.ok || !(await res.arrayBuffer()).byteLength) throw new Error("bad texture url");
const tex = engine.createTexture(resp.url, false, () => {}, (msg, ex) => console.error(msg, ex));

Defensive patterns

Strategy: try-catch

Validate before calling

const res = await fetch(url);
const buf = await res.arrayBuffer();
if (!res.ok || buf.byteLength === 0) throw new Error(`Invalid texture source: ${url}`);

Type guard

const looksLikeImage = (buf: ArrayBuffer): boolean => {
  const b = new Uint8Array(buf, 0, 4);
  return (b[0] === 0x89 && b[1] === 0x50) || (b[0] === 0xff && b[1] === 0xd8) || (b[0] === 0x47 && b[1] === 0x49);
};

Try / catch

engine.createTexture(url, false, false, scene, THREE_CONSTANTS.TRILINEAR, onLoad, (msg, ex) => {
  console.error("Native texture load failed:", msg, ex);
  fallbackTexture(url);
});

Prevention

Validate texture URLs return ok responses with image magic bytes.
Always supply onError callbacks to createTexture rather than relying on sync throws.
Test assets on every target native platform since codecs differ.

When it happens

Trigger: engine.createTexture with fromData+buffer or a URL/binary whose data the native decoder rejects (corrupt file, unsupported encoding, empty buffer), triggering the load failure callback at line 2072.

Common situations: A texture URL returns HTML/404 body instead of image bytes; a base64 data string decodes to invalid image data; native image decoding lacks a codec present in the browser build.

Related errors

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