apache/cassandra · error · RuntimeException

Unable to deserialize payload for minimum_client_driver_vers

Error message

Unable to deserialize payload for minimum_client_driver_versions_warned:

What it means

This error is thrown when the guardrail config property 'minimum_client_driver_versions_warned' cannot be parsed from its JSON string form into a Map<String,String> by Jackson. Cassandra wraps the Jackson JsonProcessingException in a RuntimeException including only the Jackson message. It means the value supplied via JMX/nodetool or config is not valid JSON matching the expected map shape.

Source

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

        }
        catch (Throwable t)
        {
            throw new RuntimeException("Unable to serialize minimum_client_driver_versions_disallowed configuration: " + t.getMessage());
        }
    }

    @Override
    public void setMinimumClientDriverVersionsWarned(String value)
    {
        try
        {
            Map<String, String> map = JsonUtils.JSON_OBJECT_MAPPER.readValue(value, new TypeReference<>() {});
            GuardrailsOptions.validateAndSanitizeClientDriverVersions(map, "minimum_client_driver_versions_warned");
            DEFAULT_CONFIG.setMinimumClientDriverVersionsWarned(map);
        }
        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());
        }
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Validate the JSON payload with a parser before calling the setter (must be a JSON object with string keys and string values)
Correct quoting when passing through shell: wrap the value in single quotes and use double quotes inside, e.g. '{"3.0.0":"cassandra-driver"}'
Read the embedded Jackson message after the colon; it pinpoints the exact character/position of the parse failure
Use the version from a config file (cassandra.yaml) instead of an inline JMX string to avoid quoting issues

Example fix

// before
setMinimumClientDriverVersionsWarned("{'4.11.0':'java-driver'}");
// after
setMinimumClientDriverVersionsWarned("{\"4.11.0\":\"java-driver\"}");

Defensive patterns

Strategy: validation

Validate before calling

String v = "{\"4.11.0\":\"java-driver\"}";
try (var p = new com.fasterxml.jackson.core.JsonFactory().createParser(v)) {
    while (p.nextToken() != null) { }
}
// additionally verify top-level object with string values before calling the setter

Type guard

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

Try / catch

try {
    guardrails.setMinimumClientDriverVersionsWarned(json);
} catch (RuntimeException e) {
    if (e.getMessage().startsWith("Unable to deserialize payload for minimum_client_driver_versions_warned")) {
        // log Jackson message after the colon, correct the JSON, retry
    } else throw e;
}

Prevention

Always test the JSON string with a parser before applying guardrail setters
Use double quotes for JSON keys and values; single-quote the whole payload in shells
Prefer cassandra.yaml config over inline JMX strings to avoid quoting issues

When it happens

Trigger: Calling setMinimumClientDriverVersionsWarned(String) with malformed JSON, valid JSON that is not an object of string-to-string (e.g. an array, number, or nested object), or a payload that fails GuardrailsOptions.validateAndSanitizeClientDriverVersions producing a JsonProcessingException.

Common situations: Operators passing nodetool/JMX values with unquoted keys, single quotes instead of double quotes, trailing commas, or shell-mangled quoting when setting guardrail thresholds for client driver versions.

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/0d4bd399f5343e90. Report an issue: GitHub.