BabylonJS/Babylon.js · error · Error

Failed to decode the KTX2 file. ${decodedData.errors}

Error message

Failed to decode the KTX2 file. ${decodedData.errors}

What it means

After validation, the KTX2 buffer is transcoded with _decodeAsync using forceRGBA. If the transcoder reports errors (unsupported format, corrupted data, missing transcoder wasm/JS), the library throws with the error list appended to the message.

Source

Thrown at packages/dev/core/src/Materials/Textures/rawTexture2DArray.functions.ts:160

        }
        buffer = new Uint8Array(await response.arrayBuffer());
    } else {
        buffer = data;
    }

    const { KhronosTextureContainer2 } = await import("../../Misc/khronosTextureContainer2");

    if (!KhronosTextureContainer2.IsValid(buffer)) {
        throw new Error("The provided data is not a valid KTX2 file.");
    }

    const container = new KhronosTextureContainer2(scene.getEngine());

    // forceRGBA: the transcoded compressed formats cannot be uploaded to an array texture yet (see above).
    const decodedData = await container._decodeAsync(buffer, { forceRGBA: true });

    if (decodedData.errors) {
        throw new Error("Failed to decode the KTX2 file. " + decodedData.errors);
    }

    const layerCount = Math.max(decodedData.layerCount ?? 1, 1);
    // mipmaps are ordered level by level, and within a level layer by layer, so the base level occupies
    // the first layerCount entries and its layers are already in ascending order.
    const baseLevel = decodedData.mipmaps.slice(0, layerCount);

    if (baseLevel.length !== layerCount) {
        throw new Error(`Failed to decode the KTX2 file: expected ${layerCount} layers for the base mip level but got ${baseLevel.length}.`);
    }

    // Every layer of a level shares the level's dimensions, and forceRGBA above means each one must be exactly
    // width * height * 4 bytes. RawTexture2DArray takes all the layers as one flat buffer and cannot detect a
    // short or mismatched layer, so validate here rather than uploading malformed data.
    const { width, height } = baseLevel[0];
    const expectedLayerByteLength = width * height * 4;

    for (const mipmap of baseLevel) {

View on GitHub (pinned to 0592b347b8)

Solutions

1. Set KhronosTextureContainer2.URLConfig to serve the KTX2 transcoder .wasm/.js/.jsm files from your CDN
2. Re-export the KTX2 with a standard UASTC/ETC1S transcode setting
3. Inspect decodedData.errors in the message for the specific codec problem
4. Read the file with the official ktx tools to confirm integrity

Example fix

// before
const tex = await CreateTexture2DArrayFromKTX2Async(scene, buffer);
// after
import { KhronosTextureContainer2 } from "@babylonjs/core/Misc/khronosTextureContainer2";
KhronosTextureContainer2.URLConfig = { jsDecoder: "/cdn/ktx2/ktx2Transcoder.js", wasmDecoder: "/cdn/ktx2/ktx2Transcoder.wasm" };
const tex = await CreateTexture2DArrayFromKTX2Async(scene, buffer);

import { KhronosTextureContainer2 } from "@babylonjs/core/Misc/khronosTextureContainer2";
KhronosTextureContainer2.URLConfig = {
  jsDecoder: "/cdn/ktx2/ktx2Transcoder.js",
  jsModuleDecoder: "/cdn/ktx2/ktx2Transcoder.jsm",
  wasmDecoder: "/cdn/ktx2/ktx2Transcoder.wasm"
};

try {
  const tex = await CreateTexture2DArrayFromKTX2Async(scene, buffer);
} catch (e) {
  if (e instanceof Error && e.message.startsWith("Failed to decode the KTX2 file")) {
    console.error("KTX2 transcode failed:", e.message);
    return createRGBAArrayTextureFallback(scene, buffer);
  }
  throw e;
}

When it happens

Trigger: KTX2 files using transcode targets or supercompression schemes the decoder cannot handle, corrupted buffers, or the KhronosTextureContainer2 wasm/JS runtime files not being served so decoding fails.

Common situations: Not configuring the KTX2 transcoder URLs (KhronosTextureContainer2.URLConfig), server missing .wasm/.js MIME types, or an exotic basis format from the exporter.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• The provided data is not a valid KTX2 file.
• Failed to decode the KTX2 file: expected ${layerCount} layer
• Failed to decode the KTX2 file: layer ${mipmap.layerIndex} o
• EXR data could not be decoded.
• Failed to fetch KTX2 file "${data}": ${response.status} ${re

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