{"record":{"id":"35342b964e5cc94b","repo":"can1357/oh-my-pi","slug":"invalid-compress-z-header","errorCode":null,"errorMessage":"Invalid compress (.Z) header","messagePattern":"Invalid compress \\(\\.Z\\) header","errorType":"exception","errorClass":"ArchiveError","httpStatus":null,"severity":"error","filePath":"packages/utils/src/ar/codecs/lzw.ts","lineNumber":104,"sourceCode":"\t\tlet capacity = Math.max(needed, Math.min(this.#limit, Math.max(64, this.#bytes.byteLength * 2)));\n\t\tif (capacity > this.#limit) {\n\t\t\tcapacity = this.#limit;\n\t\t}\n\t\tconst grown = new Uint8Array(capacity);\n\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","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/utils/src/ar/codecs/lzw.ts#L86-L122","documentation":"lzwDecompress() only decodes ncompress-style Unix compress (.Z) streams, which must begin with the two magic bytes 0x1f 0x9d followed by a flags byte. This error means the input does not start with that magic signature, so the bytes are not a .Z stream at all (or the first two bytes were lost/corrupted in transit).","triggerScenarios":"Calling lzwDecompress(bytes, maxOutput) with a Uint8Array whose bytes[0] !== 0x1f or bytes[1] !== 0x9d — e.g. passing a gzip (0x1f 0x8b), zlib (0x78), bzip2 ('BZ'), or raw LZW stream, or a .Z file whose header bytes were stripped by an upload/transfer step.","commonSituations":"Handing the function a file with a renamed .Z extension that is actually another format; concatenating or re-assembling archive members and off-by-one slicing away the 3-byte header; base64/text-mode transfers corrupting the first bytes; trying to decompress an already-uncompressed payload.","solutions":["Call isCompressZ(bytes) first and reject/handle non-matching input instead of decompressing blindly.","Verify the file is actually a compress (.Z) file (file(1) or first bytes 1f 9d); if it is gzip/zlib/deflate, use the matching codec instead.","Check that the buffer passed starts at offset 0 of the stream — no leading metadata or partial read that skipped the header.","Re-download or re-extract the file if the header bytes are corrupt (corruption during transfer)."],"exampleFix":"// before\nconst out = await lzwDecompress(data, 10_000_000);\n// after\nimport { isCompressZ, lzwDecompress } from \"@oh-my-pi/pi-utils\";\nif (!isCompressZ(data)) throw new Error(\"not a .Z stream\");\nconst out = await lzwDecompress(data, 10_000_000);","handlingStrategy":"validation","validationCode":"import { isCompressZ } from \"@oh-my-pi/pi-utils\";\nif (!isCompressZ(bytes)) throw new Error(\"Input is not a compress (.Z) stream: expected magic 0x1f 0x9d\");","typeGuard":"function isCompressZStream(bytes: Uint8Array): boolean {\n  return bytes.byteLength >= 3 && bytes[0] === 0x1f && bytes[1] === 0x9d;\n}","tryCatchPattern":"try {\n  const out = await lzwDecompress(bytes, maxOutput);\n} catch (e) {\n  if (e instanceof ArchiveError && e.message.includes(\"Invalid compress (.Z) header\")) {\n    throw new Error(\"File is not a .Z archive — check format/extension\");\n  }\n  throw e;\n}","preventionTips":["Always sniff the magic with isCompressZ() before dispatching to the .Z codec.","Route by actual format, not file extension — .Z extensions can be mislabeled gzip or raw data.","Preserve the original stream bytes end-to-end; avoid text-mode transfers that mangle headers."],"tags":["archive","lzw","bad-magic-number","input-validation"],"backgroundTag":"bad-archive-magic-number","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}