{"record":{"id":"f67183a1369f51ac","repo":"can1357/oh-my-pi","slug":"unsupported-xz-terminal-filter-id-0x-last-id-tost","errorCode":null,"errorMessage":"Unsupported XZ terminal filter ID 0x${last.id.toString(16)} (LZMA2 required)","messagePattern":"Unsupported XZ terminal filter ID 0x(.+?) \\(LZMA2 required\\)","errorType":"exception","errorClass":"ArchiveError","httpStatus":null,"severity":"error","filePath":"packages/utils/src/ar/codecs/xz.ts","lineNumber":468,"sourceCode":"\t}\n\twhile (cursor.pos < cursor.limit)\n\t\tif (bytes[cursor.pos++] !== 0) throw new ArchiveError(\"Invalid XZ stream: non-zero block header padding\");\n\tconst integritySize = checkSize(checkId);\n\tconst compressedSize = record.unpaddedSize - headerSize - integritySize;\n\tif (!Number.isSafeInteger(compressedSize) || compressedSize <= 0)\n\t\tthrow new ArchiveError(\"Invalid XZ stream: compressed block size is invalid\");\n\tif (declaredCompressed !== undefined && declaredCompressed !== compressedSize)\n\t\tthrow new ArchiveError(\"Invalid XZ stream: block compressed size mismatch\");\n\tif (declaredUncompressed !== undefined && declaredUncompressed !== record.uncompressedSize)\n\t\tthrow new ArchiveError(\"Invalid XZ stream: block uncompressed size mismatch\");\n\tconst compressedStart = offset + headerSize;\n\tconst compressedEnd = compressedStart + compressedSize;\n\tconst paddingSize = (4 - ((headerSize + compressedSize) & 3)) & 3;\n\tconst checkStart = compressedEnd + paddingSize;\n\tif (checkStart + integritySize > bytes.byteLength) throw new ArchiveError(\"Invalid XZ stream: truncated block data\");\n\tconst last = filters[filters.length - 1]!;\n\tif (last.id !== 0x21 || last.properties.byteLength !== 1)\n\t\tthrow new ArchiveError(`Unsupported XZ terminal filter ID 0x${last.id.toString(16)} (LZMA2 required)`);\n\tlet output = await lzma2Decompress(\n\t\tlast.properties[0]!,\n\t\tbytes.subarray(compressedStart, compressedEnd),\n\t\trecord.uncompressedSize,\n\t);\n\tif (output.byteLength !== record.uncompressedSize)\n\t\tthrow new ArchiveError(\"Invalid XZ stream: decoded block size mismatch\");\n\toutput = output.slice();\n\tfor (let index = filters.length - 2; index >= 0; index--) applyFilter(output, filters[index]!);\n\tfor (let index = compressedEnd; index < checkStart; index++)\n\t\tif (bytes[index] !== 0) throw new ArchiveError(\"Invalid XZ stream: non-zero block padding\");\n\tverifyCheck(checkId, output, bytes.subarray(checkStart, checkStart + integritySize));\n\tconst paddedEnd = offset + Math.ceil(record.unpaddedSize / 4) * 4;\n\tif (checkStart + integritySize !== paddedEnd)\n\t\tthrow new ArchiveError(\"Invalid XZ stream: block size does not match its index record\");\n\treturn output;\n}\n","sourceCodeStart":450,"sourceCodeEnd":486,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/utils/src/ar/codecs/xz.ts#L450-L486","documentation":"Every XZ block's filter chain must terminate in an LZMA2 filter (ID 0x21) with exactly one property byte (the dictionary size). The block declares some other terminal filter (e.g. Delta 0x03 or a BCJ filter as the last filter) or wrong property size, which this decoder does not support as a terminal coder.","triggerScenarios":"xzDecompress parses a block whose last filter id !== 0x21, or whose LZMA2 filter does not carry exactly 1 property byte.","commonSituations":"Archives compressed with filter chains this minimal decoder does not support (e.g. delta+LZMA2 chains misordered by a custom encoder), or files not actually produced by xz.","solutions":["Re-compress the archive with plain `xz -6` (default LZMA2-only chain) so the terminal filter is LZMA2.","Check your encoder's filter ordering — XZ requires LZMA2 last in the chain.","If you need arbitrary filter chains, use a full XZ implementation instead of this decoder.","Verify the file is genuinely an XZ stream (magic 0xFD '7zXZ' 0x00) and not a renamed archive."],"exampleFix":"// before\n$`custom-xz-encoder --filters delta,lzma2 --out archive.xz data.tar` // non-terminal misordering\n// after\n$`xz -6 -k -c data.tar > archive.xz` // standard LZMA2-only stream","handlingStrategy":"fallback","validationCode":"if (!isXz(bytes)) throw new Error('Not an XZ stream');\n// Non-standard filter chains cannot be detected cheaply up front; probe with the external tool if available.\nconst ok = await $`xz -t ${path}`.quiet().nothrow();\nif (ok.exitCode !== 0) throw new Error('Unsupported or invalid XZ filter chain');","typeGuard":null,"tryCatchPattern":"try {\n\treturn await xzDecompress(bytes, maxOutput);\n} catch (err) {\n\tif (err instanceof ArchiveError && /Unsupported XZ terminal filter/i.test(err.message)) {\n\t\t// fall back to the system xz binary, which supports full filter chains\n\t\tconst res = await $`xz -dc ${path}`.quiet().nothrow();\n\t\tif (res.exitCode === 0) return new Uint8Array(await res.arrayBuffer());\n\t}\n\tthrow err;\n}","preventionTips":["Produce archives with default `xz` settings (LZMA2-only chains).","Document filter-chain restrictions for any custom encoder used in your pipeline.","Detect exotic filter chains at ingest and re-encode once, up front.","Keep a system xz fallback for archives this decoder rejects."],"tags":["archive","xz","unsupported-feature","filter-chain"],"backgroundTag":"xz-unsupported-filter","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}