BabylonJS/Babylon.js · error · Error

Failed to decode the KTX2 file: expected ${layerCount} layer

Error message

Failed to decode the KTX2 file: expected ${layerCount} layers for the base mip level but got ${baseLevel.length}.

What it means

After decoding, the function slices the first layerCount mip entries as the base level. If the transcoder returned fewer (or more) entries than the declared layer count, the data does not match a 2D array layout, so it throws rather than uploading a misaligned buffer.

Source

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

        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) {
        if (!mipmap.data) {
            throw new Error(`Failed to decode the KTX2 file: layer ${mipmap.layerIndex} of the base mip level is empty.`);
        }
        if (mipmap.width !== width || mipmap.height !== height) {
            throw new Error(
                `Failed to decode the KTX2 file: layer ${mipmap.layerIndex} of the base mip level is ${mipmap.width}x${mipmap.height} but layer 0 is ${width}x${height}.`
            );
        }
        if (mipmap.data.byteLength !== expectedLayerByteLength) {

View on GitHub (pinned to 0592b347b8)

Solutions

1. Re-export the KTX2 as a proper array texture with the expected number of layers (e.g. toktx --layers N)
2. Verify layerCount in the file header matches the number of images packed
3. Log decodedData.layerCount vs mipmaps.length to diagnose the mismatch
4. Use a single-layer path (or a regular texture) when the source only has one image

Example fix

// before
// layers.ktx2 exported with only 1 image
const tex = await CreateTexture2DArrayFromKTX2Async(scene, buffer); // expects 6 layers
// after
// re-export: toktx --layers 6 --normalize layers.ktx2 img0.png ... img5.png
const tex = await CreateTexture2DArrayFromKTX2Async(scene, buffer);

// Ensure the KTX2 was exported with the expected number of array layers
const EXPECTED_LAYERS = 6;
const res = await fetch(ktx2Url);
const buf = new Uint8Array(await res.arrayBuffer());
// layerCount lives in the KTX2 header at byte offset 24 (uint32)
const layerCount = new DataView(buf.buffer, buf.byteOffset).getUint32(24, true);
if (layerCount !== EXPECTED_LAYERS) throw new Error(`Expected ${EXPECTED_LAYERS} layers, file has ${layerCount}`);

try {
  const tex = await CreateTexture2DArrayFromKTX2Async(scene, buffer);
} catch (e) {
  if (e instanceof Error && e.message.includes("layers for the base mip level")) {
    console.error("KTX2 layer count mismatch — re-export the asset as an array texture");
  } else throw e;
}

When it happens

Trigger: Decoded KTX2 whose mipmaps array length for the base level disagrees with layerCount — a single-image KTX2 used as an array, a mismatched export, or inconsistent header metadata.

Common situations: Exporting a non-array KTX2 and treating it as an array texture, tool bugs in layer/mipmap generation, or a partially transcoded file.

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. ${decodedData.errors}
• Failed to decode the KTX2 file: layer ${mipmap.layerIndex} o
• Failed to decode the KTX2 file: layer ${mipmap.layerIndex} o
• Failed to decode the KTX2 file: layer ${mipmap.layerIndex} o

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