apache/cassandra · warning

Client driver , version is below recommended minimum version

Error message

Client driver %s, version %s is below recommended minimum version %s

What it means

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.

Solutions

1. Upgrade the client driver to at least the recommended minimum version printed in the message.
2. Track the offending client via connection metadata (nodetool clientlist) and schedule its upgrade.
3. If the minimum is overly strict for your deployment, adjust the client_driver_version guardrail warn thresholds.
4. Confirm the client actually reports a proper version — an 'unset' version with a configured minimum also lands here; fix client identity reporting.

Example fix

// before (pom.xml)
<dependency>
  <groupId>com.datastax.cassandra</groupId>
  <artifactId>cassandra-driver-core</artifactId>
  <version>3.6.0</version>
</dependency>

// after — upgrade to the recommended minimum
<dependency>
  <groupId>org.apache.cassandra</groupId>
  <artifactId>java-driver-core</artifactId>
  <version>4.18.1</version>
</dependency>

// verify the driver version against server minimums before rollout
String v = sanitizeVersion(driverVersion);
if (v.equals("unset") || isBelowMinimum(v, minimumRecommendedVersion)) {
    throw new IllegalStateException("Upgrade driver before connecting: >= " + minimumRecommendedVersion);
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

• Connection with unset driver id was detected.
• Detected unknown driver id
• Can't ignore local host
• Cannot alter gc_grace_seconds of a materialized view to 0…
• Cannot DROP COMPACT STORAGE as some nodes in the cluster

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

Appendix: source

Thrown at src/java/org/apache/cassandra/db/guardrails/ClientDriverVersionGuardrail.java:121

                                   sanitizedDriverId,
                                   sanitizedDriverVersion,
                                   minimumVersionFail),
                     state);
                return;
            }
            else if (minimumVersionFail == null && disallowed.containsKey("unknown"))
            {
                fail(String.format("Detected unknown driver id: %s.", sanitizedDriverId), state);
                return;
            }
        }

        if (warned != null && !warned.isEmpty())
        {
            String minimumVersionWarn = warned.get(sanitizedDriverId);
            if (minimumVersionWarn != null && (sanitizedDriverVersion.equals("unset") || isBelowMinimum(sanitizedDriverVersion, minimumVersionWarn)))
            {
                warn(String.format("Client driver %s, version %s is below recommended minimum version %s",
                                   sanitizedDriverId,
                                   sanitizedDriverVersion,
                                   minimumVersionWarn));
            }
            else if (minimumVersionWarn == null && warned.containsKey("unknown"))
            {
                warn(String.format("Detected unknown driver id: %s", sanitizedDriverId));
            }
        }
    }

    /**
     * This method should not be used in normal circumstances as {@link #guard(String, String, ClientState)}
     * should be called directly instead.
     *
     * @param rawDriverId the value to check, driver name and version delimited by a colon.
     * @param state       client state
     */

View on GitHub (pinned to 88fd0f6a0e)