{"record":{"id":"4cd96c3174352d70","repo":"apache/cassandra","slug":"cql-version-s-is-not-supported-by-the-binary-prot","errorCode":null,"errorMessage":"CQL version %s is not supported by the binary protocol (supported version are >= 3.0.0)","messagePattern":"CQL version (.+?) is not supported by the binary protocol \\(supported version are >= 3\\.0\\.0\\)","errorType":"exception","errorClass":"ProtocolException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/transport/messages/StartupMessage.java","lineNumber":93,"sourceCode":"    public final Map<String, String> options;\n\n    public StartupMessage(Map<String, String> options)\n    {\n        super(Message.Type.STARTUP);\n        this.options = options;\n    }\n\n    @Override\n    protected Message.Response execute(QueryState state, Dispatcher.RequestTime requestTime, boolean traceRequest)\n    {\n        String cqlVersion = options.get(CQL_VERSION);\n        if (cqlVersion == null)\n            throw new ProtocolException(\"Missing value CQL_VERSION in STARTUP message\");\n\n        try\n        {\n            if (new CassandraVersion(cqlVersion).compareTo(new CassandraVersion(\"2.99.0\")) < 0)\n                throw new ProtocolException(String.format(\"CQL version %s is not supported by the binary protocol (supported version are >= 3.0.0)\", cqlVersion));\n        }\n        catch (IllegalArgumentException e)\n        {\n            throw new ProtocolException(e.getMessage());\n        }\n\n        if (options.containsKey(COMPRESSION))\n        {\n            String compression = toLowerCaseLocalized(options.get(COMPRESSION));\n            if (compression.equals(\"snappy\"))\n            {\n                if (Compressor.SnappyCompressor.instance == null)\n                    throw new ProtocolException(\"This instance does not support Snappy compression\");\n\n                if (getSource().header.version.isGreaterOrEqualTo(ProtocolVersion.V5))\n                    throw new ProtocolException(\"Snappy compression is not supported in protocol V5\");\n\n                connection.setCompressor(Compressor.SnappyCompressor.instance);","sourceCodeStart":75,"sourceCodeEnd":111,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/transport/messages/StartupMessage.java#L75-L111","documentation":"The binary protocol only speaks CQL version 3.0.0 and later; if the STARTUP message's CQL_VERSION parses to something older than 2.99.0, StartupMessage rejects it with a ProtocolException. A malformed version string also surfaces here as a ProtocolException wrapping the parse error.","triggerScenarios":"Sending a STARTUP with CQL_VERSION values like \"2.0.0\", \"1.2.0\", or unparseable strings — typically from very old clients, or ports of legacy thrift-era configs into the native protocol.","commonSituations":"Migrating ancient client libraries (pre-CQL3) to the native protocol; copying thrift connection configs; typos in the version string in hand-rolled clients.","solutions":["Set CQL_VERSION to \"3.0.0\" (or a supported 3.x value) in the STARTUP options","Upgrade or replace pre-CQL3 clients with a native-protocol-capable driver","Validate the version string parses as a valid version before sending","Audit config migration so legacy thrift settings aren't reused for the native protocol"],"exampleFix":"// before\noptions.put(\"CQL_VERSION\", \"2.0.0\"); // thrift-era\n// after\noptions.put(\"CQL_VERSION\", \"3.0.0\");","handlingStrategy":"validation","validationCode":"CassandraVersion v = new CassandraVersion(options.get(\"CQL_VERSION\"));\nif (v.compareTo(new CassandraVersion(\"2.99.0\")) < 0)\n    throw new IllegalArgumentException(\"native protocol requires CQL >= 3.0.0\");","typeGuard":null,"tryCatchPattern":"try {\n    connection.startup(options);\n} catch (ProtocolException e) {\n    if (e.getMessage().contains(\"not supported by the binary protocol\")) {\n        options.put(\"CQL_VERSION\", \"3.0.0\");\n        connection.startup(options);\n    } else throw e;\n}","preventionTips":["Use \"3.0.0\" as CQL_VERSION for all native-protocol connections","Upgrade or retire pre-CQL3 client libraries","Don't reuse thrift-era configs for native protocol connections","Validate version strings parse before sending STARTUP"],"tags":["cql","startup","protocol-version","compatibility"],"backgroundTag":"unsupported-config-value","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}