{"record":{"id":"0799b9544cd8ca1e","repo":"BabylonJS/Babylon.js","slug":"deflate-distance-out-of-range","errorCode":null,"errorMessage":"deflate: distance out of range","messagePattern":"deflate: distance out of range","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/dev/loaders/src/FBX/parsers/zlibInflate.ts","lineNumber":168,"sourceCode":"    public constructor(expectedLength: number) {\r\n        this.bytes = new Uint8Array(expectedLength);\r\n    }\r\n\r\n    public writeByte(value: number): void {\r\n        if (this.offset >= this.bytes.byteLength) {\r\n            throw new Error(\"zlib: output length mismatch\");\r\n        }\r\n        const byte = value & 0xff;\r\n        this.bytes[this.offset++] = byte;\r\n        this.adlerA += byte;\r\n        this.adlerB += this.adlerA;\r\n        this.adlerA %= ADLER_MOD;\r\n        this.adlerB %= ADLER_MOD;\r\n    }\r\n\r\n    public copy(distance: number, length: number): void {\r\n        if (distance <= 0 || distance > this.offset) {\r\n            throw new Error(\"deflate: distance out of range\");\r\n        }\r\n        for (let i = 0; i < length; i++) {\r\n            this.writeByte(this.bytes[this.offset - distance]);\r\n        }\r\n    }\r\n\r\n    public finish(): void {\r\n        if (this.offset !== this.bytes.byteLength) {\r\n            throw new Error(\"zlib: output length mismatch\");\r\n        }\r\n    }\r\n\r\n    public adler32(): number {\r\n        return ((this.adlerB << 16) | this.adlerA) >>> 0;\r\n    }\r\n}\r\n\r\nclass HuffmanTree {\r","sourceCodeStart":150,"sourceCodeEnd":186,"githubUrl":"https://github.com/BabylonJS/Babylon.js/blob/0592b347b8a4ee0236089ea86a749cacfdb266d8/packages/dev/loaders/src/FBX/parsers/zlibInflate.ts#L150-L186","documentation":"OutputWriter.copy validates that a back-reference distance is within the bytes already written: distance must be > 0 and <= the current output offset. A distance beyond what has been emitted is illegal in DEFLATE (it would read from the pre-output prefix shared with the compressor), so the library throws. This always indicates a corrupt or non-deflate bitstream, since a valid compressor never emits such a distance.","triggerScenarios":"inflateCompressedBlock decodes a length/distance pair whose decoded distance exceeds the number of bytes written so far — bitstream desynchronization (e.g. after a truncated read or wrong tree), or input that is not actually deflate data.","commonSituations":"Corrupted downloads where mid-stream bits flip; passing a random byte blob that passed the zlib header coincidence test; mixing up payload offsets so the inflater starts mid-stream; FBX assets damaged by faulty binary-merge tooling (git LFS/merge conflicts).","solutions":["Treat the file as corrupt first: try inflating it with pako or Node's zlib to confirm.","Verify the payload slice starts exactly at the compressed data (2-byte zlib header), not at an arbitrary offset.","Re-download/re-export the FBX file; check git LFS pointers and merge states for binary assets.","If you control the producer, regenerate the compressed payload with a standard zlib implementation."],"exampleFix":"// before\nconst payload = buffer.subarray(nodeOffset + 8, ...); // wrong start, mid-stream\n// after\nconst payload = buffer.subarray(nodeOffset, nodeOffset + compressedLength); // header-aligned start\ninflateZlib(payload, count);","handlingStrategy":"try-catch","validationCode":"function hasValidZlibHeader(buf: Uint8Array): boolean {\n  return buf.byteLength >= 6 && (buf[0] & 0x0f) === 8 && buf[0] >> 4 <= 7 && ((buf[0] << 8) + buf[1]) % 31 === 0;\n}\nif (!hasValidZlibHeader(payload)) throw new Error(\"not a zlib stream\");","typeGuard":"function isZlib(buf: unknown): buf is Uint8Array {\n  return buf instanceof Uint8Array && buf.byteLength >= 6 && ((buf[0] << 8) + buf[1]) % 31 === 0;\n}","tryCatchPattern":"try {\n  return inflateZlib(payload, count);\n} catch (e) {\n  if (e instanceof Error && e.message === \"deflate: distance out of range\") {\n    throw new Error(\"corrupt deflate stream (illegal back-reference) — re-export the FBX asset\");\n  }\n  throw e;\n}","preventionTips":["Start inflation exactly at the zlib header, never mid-stream.","Verify binary assets in git LFS / merge states; bad merges corrupt payloads.","Cross-validate suspicious files with Node zlib or pako.","Never hand-edit compressed FBX array payloads."],"tags":["deflate","back-reference","corrupt-data","zlib"],"backgroundTag":"deflate-distance-out-of-range","analyzedSha":"0592b347b8a4ee0236089ea86a749cacfdb266d8","analyzedAt":"2026-08-30T15:11:20.442Z","schemaVersion":2},"datasetVersion":"2026-08-30T18:17:15.746Z"}