BabylonJS/Babylon.js · error · Error

HufDecode issues

Error message

HufDecode issues

What it means

In HufDecode's overflow path, after following the table entry's pointer (`pl.p`) and scanning up to `pl.lit` candidate symbols, if no symbol matches the remaining bits (`j == pl.lit`) the bitstream cannot be represented by the code table, so the loader throws "HufDecode issues". This is the final integrity check when decoding huf-compressed EXR data.

Source

Thrown at packages/dev/core/src/Materials/Textures/Loaders/EXR/exrLoader.compression.huf.ts:395

                    if (lc >= l) {
                        if (HufCode(encodingTable[pl.p[j]]) == ((c >> (lc - l)) & ((1 << l) - 1))) {
                            lc -= l;

                            const gCode = GetCode(pl.p[j], rlc, c, lc, array, offset, outBuffer, outOffset, outBufferEndOffset);

                            if (gCode) {
                                c = gCode.c;
                                lc = gCode.lc;
                            }

                            break;
                        }
                    }
                }

                if (j == pl.lit) {
                    throw new Error("HufDecode issues");
                }
            }
        }
    }

    const i = (8 - ni) & 7;

    c >>= i;
    lc -= i;

    while (lc > 0) {
        const pl = decodingTable[(c << (HUF_DECBITS - lc)) & HUF_DECMASK];

        if (pl.len) {
            lc -= pl.len;

            const gCode = GetCode(pl.lit, rlc, c, lc, array, offset, outBuffer, outOffset, outBufferEndOffset);
            if (gCode) {

View on GitHub (pinned to 0592b347b8)

Solutions

  1. Verify the asset integrity (size/checksum) and re-download or re-export the EXR.
  2. Re-encode the EXR with a reference implementation using a non-huf compression.
  3. Check the serving pipeline for accidental content-transformations of binary files.
  4. Wrap EXR loading in try/catch with a fallback image and user-facing message.
Defensive patterns

Strategy: try-catch

Validate before calling

async function preflightExr(url) {
  const res = await fetch(url);
  const buf = new Uint8Array(await res.arrayBuffer());
  const dv = new DataView(buf.buffer);
  return buf.length > 8 && dv.getUint32(0, true) === 20000630;
}

Type guard

function isExrBuffer(data) {
  return data instanceof ArrayBuffer &&
    data.byteLength >= 8 &&
    new DataView(data).getUint32(0, true) === 20000630;
}

Try / catch

try {
  loadExrTexture('scene.exr');
} catch (e) {
  if (e instanceof Error && e.message === 'HufDecode issues') {
    console.error('EXR huf bitstream does not match its code table; asset is corrupt.');
    swapToFallbackTexture();
  } else { throw e; }
}

Prevention

When it happens

Trigger: Huf EXR bitstream contains a bit pattern that fails to match any symbol in the overflow list for a long code — payload corrupted, misaligned by earlier bad reads, or produced by a non-canonical encoder.

Common situations: Corrupted/partial downloads; EXR assets written by buggy custom encoders; binary assets altered by build tools or asset pipelines (e.g. minifiers/gzip applied twice); opening a non-EXR file with an .exr extension.

Related errors

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