What causes "Detected unknown driver id: %s" in apache/cassandra?

Check what the client sends as driver name — if it's a custom driver, register awareness of it in your guardrail config or set an explicit threshold for it.

apache/cassandra · warning

Detected unknown driver id

Error message

Detected unknown driver id: %s

What it means

ClientDriverVersionGuardrail.guard warns when the client's driver id is not one the server recognizes (no per-driver minimum configured) while the guardrail has an 'unknown' warn entry. The server cannot make any compatibility judgment about an unrecognized driver, so it flags it for operator awareness.

Solutions

Check what the client sends as driver name — if it's a custom driver, register awareness of it in your guardrail config or set an explicit threshold for it.
Upgrade the client to a mainstream driver the server recognizes if the custom one is unintentional.
Add the unknown driver id to the guardrail's warn/fail map if you want tailored thresholds for it.
Silence by adjusting the 'unknown' warn entry if this traffic is expected and safe.

Defensive patterns

Strategy: validation

Validate before calling

// ensure the client reports a recognized driver name
if (!KNOWN_DRIVER_IDS.contains(driverId)) {
    logger.warn("Driver id '{}' is not recognized by the server guardrail", driverId);
}

Prevention

Prefer supported mainstream drivers whose ids the server recognizes.
For custom drivers, configure their id in the guardrail thresholds deliberately.
Audit connection metadata to catch spoofed/misconfigured driver names.
Update guardrail config when adding new client stacks to the fleet.

When it happens

Trigger: A client reports a driverName that is not in the server's known-driver table (custom driver, niche language driver, misconfigured driver name string) and warned.containsKey("unknown") is true with no minimumVersionWarn for that id.

Common situations: In-house or experimental drivers setting a custom driver name in connection options; new driver versions ahead of the server's known list; spoofed/incorrect driver name configuration.

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

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

Appendix: source

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

            {
                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
     */
    @Override
    public void guard(String rawDriverId, @Nullable ClientState state)
    {
        if (rawDriverId == null)
        {
            guard(null, null, state);
        }

View on GitHub (pinned to 88fd0f6a0e)