apache/cassandra · error · ProtocolException

Unsupported compression type:

Error message

Unsupported compression type: 

What it means

ProtocolException thrown when the frame decoder is asked to handle a compression algorithm it does not support. Only null (no compression, CRC-protected framing) and 'lz4' (case-insensitive) are accepted in the modern (v5+) frame pipeline; any other string is rejected. This surfaces the configured compression name from the STARTUP message or config straight into a hard protocol error.

Solutions

1. Set the client's compression option to 'lz4' or disable compression (null) for protocol v5+ connections.
2. If snappy is required, keep the connection on protocol v4 or lower where the legacy envelope path applies.
3. Correct typos in the compression option value (it is compared case-insensitively but must still be exactly 'lz4').
4. Upgrade the driver if it advertises an unsupported default compression for v5.

Example fix

// before
cluster.withCompression(Compression.SNAPPY).withProtocolVersion(ProtocolVersion.V5);
// after
cluster.withCompression(Compression.LZ4).withProtocolVersion(ProtocolVersion.V5);

// client-side guard before configuring compression
String c = compressionName.toLowerCase();
if (protocolVersion.isGreaterOrEqualTo(ProtocolVersion.V5) && !(c.isEmpty() || c.equals("lz4")))
    throw new IllegalArgumentException("Only null or lz4 supported for v5+ frames");

try { session.init(); } catch (ProtocolException e) { if (e.getMessage().startsWith("Unsupported compression")) { fallbackToLz4OrNone(); } }

When it happens

Trigger: A client sends a STARTUP message (or the endpoint is configured) with a COMPRESSION option set to something other than ''/null or 'lz4' — e.g. 'snappy' on a v5+ connection using the new frame decoder path.

Common situations: Drivers configured with snappy compression against a v5+ endpoint, typo'd compression names ('Lz4 ', 'zstd'), or templates carrying settings from other systems.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• compressed_read_ahead_buffer_size must be at least 256KiB…
• Compression dictionary checksum does not match. Expected
• Compressor does not support dictionary training
• <ConfigurationException message>
• Could not create Compression for type

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

Appendix: source

Thrown at src/java/org/apache/cassandra/transport/PipelineConfigurator.java:393

    }

    protected CQLMessageHandler.MessageConsumer<Message.Request> messageConsumer()
    {
        return dispatcher;
    }

    protected Message.Decoder<Message.Request> messageDecoder()
    {
        return Message.requestDecoder();
    }

    protected FrameDecoder frameDecoder(String compression, BufferPoolAllocator allocator)
    {
        if (null == compression)
            return FrameDecoderCrc.create(allocator);
        if (compression.equalsIgnoreCase("LZ4"))
            return FrameDecoderLZ4.fast(allocator);
        throw new ProtocolException("Unsupported compression type: " + compression);
    }

    protected FrameEncoder frameEncoder(String compression)
    {
        if (Strings.isNullOrEmpty(compression))
            return FrameEncoderCrc.instance;
        if (compression.equalsIgnoreCase("LZ4"))
            return FrameEncoderLZ4.fastInstance;
        throw new ProtocolException("Unsupported compression type: " + compression);
    }

    public void configureLegacyPipeline(ChannelHandlerContext ctx, ClientResourceLimits.Allocator limits)
    {
        ChannelPipeline pipeline = ctx.channel().pipeline();
        pipeline.addBefore(ENVELOPE_ENCODER, ENVELOPE_DECODER, new Envelope.Decoder());
        pipeline.addBefore(INITIAL_HANDLER, MESSAGE_DECOMPRESSOR, Envelope.Decompressor.instance);
        pipeline.addBefore(INITIAL_HANDLER, MESSAGE_COMPRESSOR, Envelope.Compressor.instance);
        pipeline.addBefore(INITIAL_HANDLER, MESSAGE_DECODER, PreV5Handlers.ProtocolDecoder.instance);

View on GitHub (pinned to 88fd0f6a0e)