{"record":{"id":"73ba8d2a5fe03b1f","repo":"can1357/oh-my-pi","slug":"unsupported-compress-z-header-flags","errorCode":null,"errorMessage":"Unsupported compress (.Z) header flags","messagePattern":"Unsupported compress \\(\\.Z\\) header flags","errorType":"exception","errorClass":"ArchiveError","httpStatus":null,"severity":"error","filePath":"packages/utils/src/ar/codecs/lzw.ts","lineNumber":109,"sourceCode":"\t\tgrown.set(this.#bytes.subarray(0, this.#length));\n\t\tthis.#bytes = grown;\n\t}\n}\n\nfunction decode(bytes: Uint8Array, maxOutput: number): Uint8Array {\n\tif (!Number.isSafeInteger(maxOutput) || maxOutput < 0) {\n\t\tthrow new ArchiveError(\"Invalid compress (.Z) output limit\");\n\t}\n\tif (bytes.byteLength < 3) {\n\t\tthrow new ArchiveError(\"Truncated compress (.Z) header\");\n\t}\n\tif (bytes[0] !== 0x1f || bytes[1] !== 0x9d) {\n\t\tthrow new ArchiveError(\"Invalid compress (.Z) header\");\n\t}\n\n\tconst flags = bytes[2]!;\n\tif ((flags & 0x60) !== 0) {\n\t\tthrow new ArchiveError(\"Unsupported compress (.Z) header flags\");\n\t}\n\tconst maxBits = flags & 0x1f;\n\tif (maxBits < MIN_BITS || maxBits > MAX_BITS) {\n\t\tthrow new ArchiveError(`Invalid compress (.Z) maximum code width ${maxBits}`);\n\t}\n\tconst blockMode = (flags & 0x80) !== 0;\n\tconst dictionaryLimit = 2 ** maxBits;\n\tconst parents = new Uint16Array(dictionaryLimit);\n\tconst suffixes = new Uint8Array(dictionaryLimit);\n\tconst stack = new Uint8Array(dictionaryLimit);\n\tconst reader = new LsbCodeReader(bytes.subarray(3));\n\tconst output = new BoundedOutput(maxOutput, bytes.byteLength);\n\n\tlet width = MIN_BITS;\n\tlet dictionaryHead = blockMode ? FIRST_BLOCK_CODE : 256;\n\tlet needsPreviousSuffix = false;\n\n\tfor (;;) {","sourceCodeStart":91,"sourceCodeEnd":127,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/utils/src/ar/codecs/lzw.ts#L91-L127","documentation":"The third byte of a .Z stream is a flags byte; bits 0x20 and 0x40 are reserved by the compress format and must be 0. This decoder rejects streams with those reserved bits set because their meaning is undefined and no known ncompress version emits them — such a stream is either corrupt or produced by a nonstandard compressor.","triggerScenarios":"Calling lzwDecompress on a stream whose header byte bytes[2] has bit 0x20 or 0x40 set (flags & 0x60 !== 0), e.g. a corrupted third byte or output of a nonstandard/patched compress implementation.","commonSituations":"A .Z file damaged by an editor/transfer layer that flipped header bits; archives produced by exotic or buggy compress clones; misinterpreted files from non-Unix sources that coincidentally carry the 1f 9d magic.","solutions":["Treat the input as corrupt: re-obtain the .Z file from its original source and compare checksums.","Check the provenance of the file — confirm it was produced by standard ncompress (flags byte should be 0x80-0x9f range, e.g. 0x90 for 16-bit block mode).","If a custom compressor produced the stream, recompress it with standard ncompress before decoding.","Report upstream if a trusted tool reliably emits such streams; this decoder intentionally does not guess at reserved-flag semantics."],"exampleFix":"// before\nawait lzwDecompress(suspectBytes, limit); // throws on flags & 0x60\n// after\nconst flags = suspectBytes[2] ?? 0;\nif ((flags & 0x60) !== 0) {\n  console.warn(\"nonstandard .Z flags, re-fetching/recompressing file\");\n}\nawait lzwDecompress(suspectBytes, limit);","handlingStrategy":"try-catch","validationCode":"const flags = bytes[2] ?? 0;\nif ((flags & 0x60) !== 0) throw new Error(\"Nonstandard .Z header flags 0x\" + flags.toString(16) + \" — re-acquire file\");","typeGuard":"function hasSupportedZFlags(bytes: Uint8Array): boolean {\n  return bytes.byteLength >= 3 && (bytes[2]! & 0x60) === 0;\n}","tryCatchPattern":"try {\n  return await lzwDecompress(bytes, maxOutput);\n} catch (e) {\n  if (e instanceof ArchiveError && e.message.includes(\"Unsupported compress (.Z) header flags\")) {\n    throw new Error(\".Z stream uses reserved header flags; source file is corrupt or nonstandard\");\n  }\n  throw e;\n}","preventionTips":["Verify archive checksums at ingest time so corruption is caught before decompression.","Standard ncompress flags are in the 0x80-0x9f range; flag inputs outside it early.","Only accept .Z files from compressors you control or trust."],"tags":["archive","lzw","corrupt-header","unsupported-feature"],"backgroundTag":"unsupported-archive-header-flags","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}