apache/cassandra · error · ProtocolException

Unknown compression algorithm

Error message

Unknown compression algorithm: %s

What it means

The STARTUP message's COMPRESSION option must be one of the recognized algorithms ('snappy' or 'lz4'). Any other value causes Cassandra to throw this ProtocolException, formatting the unrecognized algorithm name into the message, and the connection is rejected during handshake.

Solutions

1. Set the client's compression option to 'lz4' (supported in all versions)
2. Use 'snappy' only if the client will negotiate protocol V4 or lower and Snappy is available
3. Remove the COMPRESSION option entirely to connect without compression

Example fix

// before (custom client STARTUP options)
options.put(StartupMessage.COMPRESSION, "zstd");
// after
options.put(StartupMessage.COMPRESSION, "lz4");

const ALLOWED = ['snappy','lz4'];
if (compression && !ALLOWED.includes(compression.toLowerCase())) throw new Error('Unsupported Cassandra compression: ' + compression);

function isCassandraCompression(v) { return typeof v === 'string' && ['snappy','lz4'].includes(v.toLowerCase()); }

catch ProtocolException 'Unknown compression algorithm' during connect and retry with COMPRESSION unset

When it happens

Trigger: Client sends STARTUP with an option like COMPRESSION=zstd, COMPRESSION=gzip, or any typo/other string that is neither 'snappy' nor 'lz4'.

Common situations: Driver misconfiguration using an algorithm Cassandra's native protocol does not support (e.g. zstd); typos in connection options in custom clients; copy-pasting compression settings from other databases into a Cassandra driver config.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Invalid uncompressed frame length
• Provided frame does not appear to be LZ4 compressed
• Provided frame does not appear to be Snappy compressed
• Snappy compression is not supported in protocol V5
• This instance does not support Snappy compression

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

Appendix: source

Thrown at src/java/org/apache/cassandra/transport/messages/StartupMessage.java:119

        {
            String compression = toLowerCaseLocalized(options.get(COMPRESSION));
            if (compression.equals("snappy"))
            {
                if (Compressor.SnappyCompressor.instance == null)
                    throw new ProtocolException("This instance does not support Snappy compression");

                if (getSource().header.version.isGreaterOrEqualTo(ProtocolVersion.V5))
                    throw new ProtocolException("Snappy compression is not supported in protocol V5");

                connection.setCompressor(Compressor.SnappyCompressor.instance);
            }
            else if (compression.equals("lz4"))
            {
                connection.setCompressor(Compressor.LZ4Compressor.instance);
            }
            else
            {
                throw new ProtocolException(String.format("Unknown compression algorithm: %s", compression));
            }
        }

        connection.setThrowOnOverload("1".equals(options.get(THROW_ON_OVERLOAD)));

        ClientState clientState = state.getClientState();
        clientState.setClientOptions(options);
        String driverName = options.get(DRIVER_NAME);
        String driverVersion = options.get(DRIVER_VERSION);
        if (null != driverName)
        {
            clientState.setDriverName(driverName);
            clientState.setDriverVersion(driverVersion);
        }

        Guardrails.minimumClientDriverVersion.guard(driverName, driverVersion, clientState);

        IAuthenticator authenticator = DatabaseDescriptor.getAuthenticator();

View on GitHub (pinned to 88fd0f6a0e)