pixijs/pixijs · error · Error

Unsupported transcoderFormat: ${transcoderFormat}

Error message

Unsupported transcoderFormat: ${transcoderFormat}

What it means

gpuFormatToKTXBasisTranscoderFormat() maps a GPU texture format to a Basis transcoder-target name. Only six formats are mapped (bc3-rgba-unorm, bc7-rgba-unorm, etc2-rgba8unorm, astc-4x4-unorm, rgba8unorm, rg11b10ufloat). The KTX2 worker calls it during init() with basisTranscodedTextureFormat — the first entry in preferredTranscodedFormat that the device supports. If the device supports none of the five preferred formats, basisTranscodedTextureFormat is undefined and this throws 'Unsupported transcoderFormat: undefined'.

Source

Thrown at src/compressed-textures/ktx2/utils/gpuFormatToKTXBasisTranscoderFormat.ts:24

    // Uncompressed
    rgba8unorm: 'RGBA32',
    rg11b10ufloat: 'R11F_G11F_B10F',
};

/**
 * @param transcoderFormat
 * @internal
 */
export function gpuFormatToKTXBasisTranscoderFormat(transcoderFormat: string): string
{
    const format = gpuFormatToBasisTranscoderFormatMap[transcoderFormat];

    if (format)
    {
        return format;
    }

    throw new Error(`Unsupported transcoderFormat: ${transcoderFormat}`);
}

View on GitHub (pinned to 4b141e3ced)

Solutions

1. Ensure the rendering context supports at least one of bc7-rgba-unorm, astc-4x4-unorm, etc2-rgba8unorm, bc3-rgba-unorm, or rgba8unorm (rgba8unorm is universally available, so its absence usually means supportedFormats wasn't built correctly).
2. Avoid KTX2/Basis textures on devices whose only compressed format is BC1/ETC1, or extend gpuFormatToBasisTranscoderFormatMap and the preferredTranscodedFormat list.
3. Verify the supportedFormats array passed to the worker actually includes rgba8unorm as a guaranteed fallback.

Example fix

// before: device supports only BC1 -> worker init throws 'Unsupported transcoderFormat: undefined'
loadKTX2onWorker(url, ['bc1-rgba-unorm']);

// after: include rgba8unorm so a preferred format always resolves
loadKTX2onWorker(url, ['bc1-rgba-unorm', 'rgba8unorm']);

const PREFERRED = ['bc7-rgba-unorm','astc-4x4-unorm','etc2-rgba8unorm','bc3-rgba-unorm','rgba8unorm'];
function pickTranscoderFormat(supported: readonly string[]): string | undefined {
  return PREFERRED.find(f => supported.includes(f));
}
// Before loading KTX2, ensure pickTranscoderFormat(supported) is defined.

function hasBasisFallback(supported: readonly string[]): boolean {
  return ['bc7-rgba-unorm','astc-4x4-unorm','etc2-rgba8unorm','bc3-rgba-unorm','rgba8unorm']
    .some(f => supported.includes(f));
}

try { await Assets.load('tex.ktx2'); }
catch (e) {
  if (e instanceof Error && e.message.startsWith('Unsupported transcoderFormat')) {
    // device supports none of the preferred formats; load an uncompressed fallback
    return Assets.load('tex.png');
  } throw e;
}

When it happens

Trigger: KTX2 worker init when the device's supportedFormats intersect none of the five preferred formats (bc7, astc-4x4, etc2-rgba8, bc3-rgba, rgba8unorm) — e.g. a device exposing only BC1/DXT1 or only ETC1. Also fires if a custom supportedFormats configuration yields a format not in the six-entry transcoder map.

Common situations: Headless/older software renderers; devices whose only compressed format is BC1 or ETC1; misconfigured supportedFormats; WebGPU adapter exposing an unusual compressed-format subset.

Related errors

• Unable to transcode basis texture.
• Failed to load Basis texture: ${url}
• Failed to load KTX(2) texture: ${url}
• [WorkerManager.loadImageBitmap] Failed to fetch ${url}: ${re
• startTranscoding failed

AI-assisted analysis of pixijs/pixijs@4b141e3ced (2026-08-12). Data as JSON: /api/errors/2cf1ec8f8aa3b2c6. Report an issue: GitHub.