{"record":{"id":"436b85f16b81de8a","repo":"can1357/oh-my-pi","slug":"invalid-compress-z-maximum-code-width-maxbits","errorCode":null,"errorMessage":"Invalid compress (.Z) maximum code width ${maxBits}","messagePattern":"Invalid compress \\(\\.Z\\) maximum code width (.+?)","errorType":"exception","errorClass":"ArchiveError","httpStatus":null,"severity":"error","filePath":"packages/utils/src/ar/codecs/lzw.ts","lineNumber":113,"sourceCode":"\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 (;;) {\n\t\tconst code = reader.read(width);\n\t\tif (code === undefined) {\n\t\t\treader.assertFinalPadding();\n\t\t\treturn output.finish();","sourceCodeStart":95,"sourceCodeEnd":131,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/utils/src/ar/codecs/lzw.ts#L95-L131","documentation":"The low 5 bits of the .Z flags byte encode the maximum LZW code width, which must be between 9 (MIN_BITS) and 16 (MAX_BITS) bits for this decoder. This error means the header declares a code width outside that range, so the stream is not a valid compress stream this library can decode.","triggerScenarios":"Calling lzwDecompress on a stream where (bytes[2] & 0x1f) is < 9 or > 16 — typically because the flags byte is corrupt (e.g. 0x00), the file is not really a .Z stream despite matching magic, or a hypothetical >16-bit compressor produced it.","commonSituations":"Header corruption from a bad transfer or truncated/partial file where the third byte was zeroed; archives created with nonstandard LZW variants using different bit widths; fuzzed or adversarial inputs.","solutions":["Verify the flags byte: a valid ncompress file typically has bytes[2] in 0x88-0x9f (block mode, 9-16 max bits); a value like 0x80 means width 0 and is corrupt.","Re-acquire the archive and validate with `compress -d` or `file` before decoding.","If the data uses a nonstandard LZW width, decode it with a dedicated LZW library rather than this .Z decoder.","Check the code path did not overwrite/shift the header bytes before calling (e.g. wrong slice offset)."],"exampleFix":"// before\nawait lzwDecompress(bytes, maxOutput);\n// after\nconst maxBits = (bytes[2] ?? 0) & 0x1f;\nif (maxBits < 9 || maxBits > 16) {\n  throw new Error(`corrupt .Z header: max code width ${maxBits}`);\n}\nawait lzwDecompress(bytes, maxOutput);","handlingStrategy":"validation","validationCode":"const maxBits = (bytes[2] ?? 0) & 0x1f;\nif (maxBits < 9 || maxBits > 16) throw new Error(`Corrupt .Z header: max code width ${maxBits} not in [9,16]`);","typeGuard":"function hasValidZMaxBits(bytes: Uint8Array): boolean {\n  if (bytes.byteLength < 3) return false;\n  const maxBits = bytes[2]! & 0x1f;\n  return maxBits >= 9 && maxBits <= 16;\n}","tryCatchPattern":"try {\n  return await lzwDecompress(bytes, maxOutput);\n} catch (e) {\n  if (e instanceof ArchiveError && e.message.includes(\"maximum code width\")) {\n    throw new Error(\".Z header declares an impossible code width — file is corrupt\");\n  }\n  throw e;\n}","preventionTips":["Sanity-check the flags byte (0x88-0x9f for typical block-mode files) before decoding.","Treat any .Z whose third byte is 0x00 or low-bit garbage as corrupt at ingest.","Keep raw bytes intact — never rebuild the stream buffer byte-by-byte."],"tags":["archive","lzw","corrupt-header","input-validation"],"backgroundTag":"invalid-compress-header","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}