{"record":{"id":"2cf1ec8f8aa3b2c6","repo":"pixijs/pixijs","slug":"unsupported-transcoderformat-transcoderformat-2cf1ec","errorCode":null,"errorMessage":"Unsupported transcoderFormat: ${transcoderFormat}","messagePattern":"Unsupported transcoderFormat: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/compressed-textures/ktx2/utils/gpuFormatToKTXBasisTranscoderFormat.ts","lineNumber":24,"sourceCode":"    // Uncompressed\n    rgba8unorm: 'RGBA32',\n    rg11b10ufloat: 'R11F_G11F_B10F',\n};\n\n/**\n * @param transcoderFormat\n * @internal\n */\nexport function gpuFormatToKTXBasisTranscoderFormat(transcoderFormat: string): string\n{\n    const format = gpuFormatToBasisTranscoderFormatMap[transcoderFormat];\n\n    if (format)\n    {\n        return format;\n    }\n\n    throw new Error(`Unsupported transcoderFormat: ${transcoderFormat}`);\n}\n","sourceCodeStart":6,"sourceCodeEnd":26,"githubUrl":"https://github.com/pixijs/pixijs/blob/4b141e3ced7255b39c2114b6bca03421a37b2363/src/compressed-textures/ktx2/utils/gpuFormatToKTXBasisTranscoderFormat.ts#L6-L26","documentation":"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'.","triggerScenarios":"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.","commonSituations":"Headless/older software renderers; devices whose only compressed format is BC1 or ETC1; misconfigured supportedFormats; WebGPU adapter exposing an unusual compressed-format subset.","solutions":["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).","Avoid KTX2/Basis textures on devices whose only compressed format is BC1/ETC1, or extend gpuFormatToBasisTranscoderFormatMap and the preferredTranscodedFormat list.","Verify the supportedFormats array passed to the worker actually includes rgba8unorm as a guaranteed fallback."],"exampleFix":"// before: device supports only BC1 -> worker init throws 'Unsupported transcoderFormat: undefined'\nloadKTX2onWorker(url, ['bc1-rgba-unorm']);\n\n// after: include rgba8unorm so a preferred format always resolves\nloadKTX2onWorker(url, ['bc1-rgba-unorm', 'rgba8unorm']);","handlingStrategy":"validation","validationCode":"const PREFERRED = ['bc7-rgba-unorm','astc-4x4-unorm','etc2-rgba8unorm','bc3-rgba-unorm','rgba8unorm'];\nfunction pickTranscoderFormat(supported: readonly string[]): string | undefined {\n  return PREFERRED.find(f => supported.includes(f));\n}\n// Before loading KTX2, ensure pickTranscoderFormat(supported) is defined.","typeGuard":"function hasBasisFallback(supported: readonly string[]): boolean {\n  return ['bc7-rgba-unorm','astc-4x4-unorm','etc2-rgba8unorm','bc3-rgba-unorm','rgba8unorm']\n    .some(f => supported.includes(f));\n}","tryCatchPattern":"try { await Assets.load('tex.ktx2'); }\ncatch (e) {\n  if (e instanceof Error && e.message.startsWith('Unsupported transcoderFormat')) {\n    // device supports none of the preferred formats; load an uncompressed fallback\n    return Assets.load('tex.png');\n  } throw e;\n}","preventionTips":["Always include rgba8unorm in your supportedFormats fallback list so a preferred format always resolves.","Feature-detect before deciding to use Basis/KTX2 on a given device.","Don't pass only exotic formats (BC1/ETC1) to loadKTX2onWorker."],"tags":["ktx2","basis","transcoder","worker","gpu-capabilities"],"backgroundTag":null,"analyzedSha":"4b141e3ced7255b39c2114b6bca03421a37b2363","analyzedAt":"2026-08-12T17:27:29.507Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}