{"record":{"id":"430cded9b51c7207","repo":"apache/cassandra","slug":"client-driver-s-version-s-is-below-recommended","errorCode":null,"errorMessage":"Client driver %s, version %s is below recommended minimum version %s","messagePattern":"Client driver (.+?), version (.+?) is below recommended minimum version (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/java/org/apache/cassandra/db/guardrails/ClientDriverVersionGuardrail.java","lineNumber":121,"sourceCode":"                                   sanitizedDriverId,\n                                   sanitizedDriverVersion,\n                                   minimumVersionFail),\n                     state);\n                return;\n            }\n            else if (minimumVersionFail == null && disallowed.containsKey(\"unknown\"))\n            {\n                fail(String.format(\"Detected unknown driver id: %s.\", sanitizedDriverId), state);\n                return;\n            }\n        }\n\n        if (warned != null && !warned.isEmpty())\n        {\n            String minimumVersionWarn = warned.get(sanitizedDriverId);\n            if (minimumVersionWarn != null && (sanitizedDriverVersion.equals(\"unset\") || isBelowMinimum(sanitizedDriverVersion, minimumVersionWarn)))\n            {\n                warn(String.format(\"Client driver %s, version %s is below recommended minimum version %s\",\n                                   sanitizedDriverId,\n                                   sanitizedDriverVersion,\n                                   minimumVersionWarn));\n            }\n            else if (minimumVersionWarn == null && warned.containsKey(\"unknown\"))\n            {\n                warn(String.format(\"Detected unknown driver id: %s\", sanitizedDriverId));\n            }\n        }\n    }\n\n    /**\n     * This method should not be used in normal circumstances as {@link #guard(String, String, ClientState)}\n     * should be called directly instead.\n     *\n     * @param rawDriverId the value to check, driver name and version delimited by a colon.\n     * @param state       client state\n     */","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/db/guardrails/ClientDriverVersionGuardrail.java#L103-L139","documentation":"ClientDriverVersionGuardrail.guard warns when the connecting client's driver version is below a configured recommended minimum for that driver id (or the version is 'unset' while a minimum is configured). This is the warn (not fail) path of the client_driver_version guardrail, allowing the connection but flagging outdated clients.","triggerScenarios":"Connection from a driver whose sanitized version compares lower than guardrails.client_driver_version.warn's threshold for the reported driver id; e.g. warned map has {\"java driver\":\"3.x\"} and a client reports java driver 3.10; also triggers when version is unset but a per-driver warn threshold exists.","commonSituations":"Clusters upgraded to versions requiring newer drivers while applications still run old driver releases; forgotten dependency bumps after server upgrade; heterogeneous fleets where some services lag behind.","solutions":["Upgrade the client driver to at least the recommended minimum version printed in the message.","Track the offending client via connection metadata (nodetool clientlist) and schedule its upgrade.","If the minimum is overly strict for your deployment, adjust the client_driver_version guardrail warn thresholds.","Confirm the client actually reports a proper version — an 'unset' version with a configured minimum also lands here; fix client identity reporting."],"exampleFix":"// before (pom.xml)\n<dependency>\n  <groupId>com.datastax.cassandra</groupId>\n  <artifactId>cassandra-driver-core</artifactId>\n  <version>3.6.0</version>\n</dependency>\n\n// after — upgrade to the recommended minimum\n<dependency>\n  <groupId>org.apache.cassandra</groupId>\n  <artifactId>java-driver-core</artifactId>\n  <version>4.18.1</version>\n</dependency>","handlingStrategy":"validation","validationCode":"// verify the driver version against server minimums before rollout\nString v = sanitizeVersion(driverVersion);\nif (v.equals(\"unset\") || isBelowMinimum(v, minimumRecommendedVersion)) {\n    throw new IllegalStateException(\"Upgrade driver before connecting: >= \" + minimumRecommendedVersion);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin and regularly bump driver versions in dependency management.","After server upgrades, review the guardrail's recommended minimums and upgrade clients.","Use nodetool clientlist to discover which apps connect with old drivers.","Add CI checks that fail builds when the driver dependency drops below the fleet minimum."],"tags":["cassandra","guardrails","driver","version","upgrade"],"backgroundTag":"deprecated-api-usage","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"}