Troubleshooting & Frequently Asked Questions

This guide covers common errors, edge cases, and questions when integrating xz.zig.

1. Common Errors & Solutions

`error.InvalidMagic`

Cause: The input does not begin with the 6-byte XZ stream header magic (FD 37 7A 58 5A 00).
Common Cause: You may be passing a raw LZMA2 stream, a legacy .lzma file, or a .7z archive rather than an .xz container file.
Fix: Use lzma2.zig for raw LZMA2 streams or legacy .lzma files, or ensure the file is an .xz container.

`error.ChecksumMismatch`

Cause: The computed block check (CRC32, CRC64, or SHA-256) does not match the check bytes stored in the block footer.
Common Cause: File corruption, incomplete download, or disk write error.

`error.OutputTooSmall`

Cause: When using compressInto() or decompressInto(), the destination buffer provided by the caller is too small.
Fix: Provide a larger buffer or use xz.compress() / xz.decompress() which dynamically allocate memory on the heap.

`error.ExceededSizeLimit`

Cause: Decompression produced more uncompressed bytes than permitted by max_output_size.
Fix: If the payload is trusted, increase max_output_size in DecompressOptions.

`error.UnsupportedFilter`

Cause: The block header specifies a filter ID that is not implemented (e.g., ARM, ARM-Thumb, SPARC, or IA-64 BCJ filters).
Supported Filters: LZMA2 (0x21), Delta (0x03), and x86 BCJ (0x04).

2. Frequently Asked Questions (FAQ)

What is the difference between `lzma2.zig` and `xz.zig`?

lzma2.zig: Codec library for raw LZMA1/LZMA2 range-coded chunks and legacy .lzma Alone files.
xz.zig: Container library implementing .xz files (stream framing, block headers, CRC32/CRC64/SHA-256 integrity checks, Delta/BCJ filters, index tables, and footers), using lzma2.zig as its LZMA2 codec dependency.

Can `xz.zig` decompress files generated by standard XZ utilities?

Yes! xz.zig implements the official XZ File Format Specification (Version 1.0.4) and decompresses standard .xz containers cleanly.