apache/cassandra · error · IllegalArgumentException

Invalid version entries for

Error message

Invalid version entries for <guardrailName> guardrail, they do not follow semver: <invalidEntries>

What it means

Driver-name-to-version maps configured for guardrails (e.g. driver version guardrails) must follow semver. validateVersionMap sanitizes each entry and collects keys whose version fails isValidVersion; if any remain, IllegalArgumentException is thrown listing the offending keys.

Solutions

1. Rewrite each version as valid semver (e.g. '3.10.0').
2. Remove entries with non-semver versions from the map.
3. Re-validate configuration at startup.

Example fix

// before
driver_versions:
  cassandra-java-driver: 3.x
// after
driver_versions:
  cassandra-java-driver: 3.10.0

for (Map.Entry<String,String> e : versions.entrySet())
    if (!GuardrailsOptions.isValidVersion(e.getValue()))
        throw new IllegalArgumentException("Version for " + e.getKey() + " is not semver: " + e.getValue());

try { options.validate(); } catch (IllegalArgumentException e) { LOG.error("driver version guardrail invalid: {}", e.getMessage()); }

When it happens

Trigger: Configuring a driver version guardrail map (driver_name -> version string) in cassandra.yaml with non-semver versions like '3.x', 'latest', 'v1.2', or '1.2.3.4'.

Common situations: Typo'd or human-style version strings in YAML; using marketing names like 'latest' instead of concrete semver versions; copying versions from package managers that allow loose formats.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Invalid value for : minimum allowed value is 3, as CMS…
• Invalid value for : negative values are not allowed…
• Invalid value for data_disk_usage_max_disk_size
• Invalid value for data_disk_usage_max_disk_size: 0 is not…
• Invalid value for : null is not allowed

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

Appendix: source

Thrown at src/java/org/apache/cassandra/config/GuardrailsOptions.java:1726

    }

    @VisibleForTesting
    public static void validateAndSanitizeClientDriverVersions(Map<String, String> map, String guardrailName)
    {
        if (map == null || map.isEmpty())
            return;

        List<String> invalidEntries = new ArrayList<>();

        for (Map.Entry<String, String> entry : map.entrySet())
        {
            String sanitized = sanitizeVersion(entry.getValue());
            if (!isValidVersion(sanitized))
                invalidEntries.add(entry.getKey());
        }

        if (!invalidEntries.isEmpty())
            throw new IllegalArgumentException("Invalid version entries for " + guardrailName + " guardrail, they do not follow semver: " + invalidEntries);

        map.replaceAll((driver, version) -> sanitizeVersion(version));
    }

    public static boolean isValidVersion(String version)
    {
        if (version == null)
            return false;

        // try to construct it
        try
        {
            new Semver(version);
        }
        catch (Throwable t)
        {
            return false;
        }

View on GitHub (pinned to 88fd0f6a0e)