apache/cassandra · error · java.io.IOException

Decompression failed due to

Error message

Decompression failed due to 

What it means

Thrown by ZstdDictionaryCompressor.uncompress when Zstd.decompressFastDict completes but returns an error code (Zstd.isError(dsz) is true). The message includes Zstd.getErrorName(dsz) identifying the exact zstd-level failure such as dstSizeTooSmall, srcSizeWrong, or corruption_detected. Unlike error 1360, this is a zstd error code rather than a thrown Java exception.

Source

Thrown at src/java/org/apache/cassandra/io/compress/ZstdDictionaryCompressor.java:161

        if (dictionary == null)
        {
            return super.uncompress(input, inputOffset, inputLength, output, outputOffset);
        }

        int dsz;
        try
        {
            dsz = (int) Zstd.decompressFastDict(output, outputOffset,
                                                input, inputOffset, inputLength,
                                                dictionary.dictionaryForDecompression());
        }
        catch (Exception e)
        {
            throw new IOException("Decompression failed", e);
        }

        if (Zstd.isError(dsz))
            throw new IOException("Decompression failed due to " + Zstd.getErrorName(dsz));

        return dsz;
    }

    @Override
    public void uncompress(ByteBuffer input, ByteBuffer output) throws IOException
    {
        if (dictionary == null)
        {
            super.uncompress(input, output);
            return;
        }

        try
        {
            // Zstd compressors expect only direct bytebuffer. See ZstdCompressorBase.preferredBufferType and supports
            int decompressedSize = (int) Zstd.decompressDirectByteBufferFastDict(output, output.position(), output.limit() - output.position(),
                                                                                 input, input.position(), input.limit() - input.position(),

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Read the specific zstd error name in the message (after 'due to ') to identify the failure
2. If the error is dstSizeTooSmall, allocate a larger output buffer (use the file's compressed metadata / chunkLength)
3. If srcSizeWrong, ensure the inputLength exactly matches the stored compressed chunk length
4. Treat the data as corrupt and re-fetch from a replica

Example fix

// before
byte[] out = new byte[guessedSize];
int n = ...;
compressor.uncompress(in, out, 0); // may fail with dstSizeTooSmall
// after
int outSize = compressedChunk.uncompressedLength(); // from metadata
byte[] out = new byte[outSize];
compressor.uncompress(in, out, 0);

if (output.length < compressedChunk.uncompressedLength()) throw new IllegalArgumentException("output buffer too small");

boolean isZstdError(int code) { return code < 0; }

try { compressor.uncompress(input, output, 0); } catch (IOException e) { // message contains "Decompression failed due to <ZstdErrorName>"; parse and branch on error name }

When it happens

Trigger: uncompress(byte[], byte[], int) is called with an output buffer smaller than the decompressed size, an input length that does not match the compressed frame size, or corrupted input bytes — Zstd returns an error code instead of throwing.

Common situations: Underestimating the decompressed buffer size when using recomputedLength; passing concatenated or misaligned compressed chunks; bit-rot or partial disk reads.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Decompression failed
• Decompression failed due to
• Compression failed
• Decompression failed
• Decompressed lengths mismatch

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/c45dd34b6a378dca. Report an issue: GitHub.