apache/cassandra · error · RuntimeException

Unable to deserialize minimum_client_driver_versions_disallo

Error message

Unable to deserialize minimum_client_driver_versions_disallowed:

What it means

Thrown when the guardrail property 'minimum_client_driver_versions_disallowed' fails to deserialize from its JSON string into a Map<String,String> via Jackson, or fails validation during GuardrailsOptions.validateAndSanitizeClientDriverVersions with a JsonProcessingException. The original exception is wrapped in a RuntimeException with only Jackson's message appended.

Source

Thrown at src/java/org/apache/cassandra/db/guardrails/Guardrails.java:1973

        }
        catch (JsonProcessingException t)
        {
            throw new RuntimeException("Unable to deserialize payload for minimum_client_driver_versions_warned: " + t.getMessage());
        }
    }

    @Override
    public void setMinimumClientDriverVersionsDisallowed(String value)
    {
        try
        {
            Map<String, String> map = JsonUtils.JSON_OBJECT_MAPPER.readValue(value, new TypeReference<>() {});
            GuardrailsOptions.validateAndSanitizeClientDriverVersions(map, "minimum_client_driver_versions_disallowed");
            DEFAULT_CONFIG.setMinimumClientDriverVersionsDisallowed(map);
        }
        catch (JsonProcessingException t)
        {
            throw new RuntimeException("Unable to deserialize minimum_client_driver_versions_disallowed: " + t.getMessage());
        }
    }

    @Override
    public boolean getPreparedStatementsRequireParametersWarned()
    {
        return DEFAULT_CONFIG.getPreparedStatementsRequireParametersWarned();
    }

    @Override
    public boolean getPreparedStatementsRequireParametersEnabled()
    {
        return DEFAULT_CONFIG.getPreparedStatementsRequireParametersEnabled();
    }

    @Override
    public void setPreparedStatementsRequireParametersWarned(boolean warned)
    {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Ensure the payload is a JSON object with string-to-string entries, e.g. {"3.0.0":"cassandra-driver"}
Parse-test the string with a JSON linter before applying it
Check the Jackson message after the trailing colon for the exact parse offset
Prefer setting this guardrail in cassandra.yaml where quoting is simpler

Example fix

// before
setMinimumClientDriverVersionsDisallowed("{\"2.0.0\" = \"datastax-java-driver\"}");
// after
setMinimumClientDriverVersionsDisallowed("{\"2.0.0\":\"datastax-java-driver\"}");

Defensive patterns

Strategy: validation

Validate before calling

boolean ok(String s) {
    try {
        JsonUtils.JSON_OBJECT_MAPPER.readValue(s, new com.fasterxml.jackson.core.type.TypeReference<java.util.Map<String,String>>() {});
        return true;
    } catch (Exception e) { return false; }
}

Type guard

boolean isStringToStringMap(String s) {
    try {
        java.util.Map<?,?> m = JsonUtils.JSON_OBJECT_MAPPER.readValue(s, java.util.Map.class);
        return m.values().stream().allMatch(v -> v instanceof String);
    } catch (Exception e) { return false; }
}

Try / catch

try {
    guardrails.setMinimumClientDriverVersionsDisallowed(json);
} catch (RuntimeException e) {
    if (e.getMessage().startsWith("Unable to deserialize minimum_client_driver_versions_disallowed")) {
        // fix JSON per the embedded Jackson message and retry
    } else throw e;
}

Prevention

Emit strict JSON (double quotes, no trailing commas) from config tooling
Round-trip the value through the same Jackson mapper used by Cassandra before setting it
Avoid YAML-style 'key: value' syntax when setting guardrail properties

When it happens

Trigger: Calling setMinimumClientDriverVersionsDisallowed(String) with a value that is not valid JSON, or valid JSON of a shape other than Map<String,String> (array, scalar, non-string values).

Common situations: Automated config tooling emitting YAML-style maps ('key: value') instead of JSON objects; double-escaping issues when setting the value over JMX or in scripts.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

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