apache/cassandra · error · ConfigurationException

Invalid value for environment variable '${key}': expected on

Error message

Invalid value for environment variable '${key}': expected one of ${enumConstants} (case-insensitive) but was '${value}'

What it means

Thrown by CassandraRelevantEnv.getEnum when an environment variable's value cannot be parsed as a constant of the requested enum class (case-insensitively when toUppercase is set). It wraps the IllegalArgumentException from Enum.valueOf into a Cassandra ConfigurationException with the expected values listed.

Source

Thrown at src/java/org/apache/cassandra/config/CassandraRelevantEnv.java:88

    {
        return Optional.ofNullable(System.getenv(key)).map(Boolean::parseBoolean).orElse(defaultValue);
    }

    public String getKey() {
        return key;
    }

    public <T extends Enum<T>> T getEnum(boolean toUppercase, Class<T> enumClass, String defaultVal)
    {
        String value = System.getenv(key);
        value = value == null ? defaultVal : value;
        try
        {
            return Enum.valueOf(enumClass, toUppercase ? toUpperCaseLocalized(value) : value);
        }
        catch (IllegalArgumentException e)
        {
            throw new ConfigurationException(String.format("Invalid value for environment variable '%s': " +
                                                           "expected one of %s (case-insensitive) but was '%s'",
                                                           key, Arrays.toString(enumClass.getEnumConstants()), value));
        }
    }
}

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Set the env var to one of the enum constants exactly as listed in the exception message
Enable/honor case-insensitive parsing (toUppercase) or match the constant's case
Verify the value is supported in your Cassandra version
Catch ConfigurationException at startup and log a friendly message listing valid values

Example fix

// before
export JVM_EXTRA_OPTS=... CASSANDRA_DISK_FAILURE_POLICY=stop_all
// after
export CASSANDRA_DISK_FAILURE_POLICY=stop

Defensive patterns

Strategy: validation

Validate before calling

String v = System.getenv("CASSANDRA_DISK_FAILURE_POLICY");
Set<String> valid = Arrays.stream(DiskFailurePolicy.values())
    .map(Enum::name).collect(Collectors.toSet());
if (v != null && !valid.contains(v.toUpperCase(Locale.ROOT)))
    throw new IllegalArgumentException("Bad env value: " + v);

Try / catch

try {
    policy = CassandraRelevantEnv.SOME_ENUM.getEnum(DiskFailurePolicy.class);
} catch (ConfigurationException e) {
    logger.error("Fix the environment variable", e);
    policy = DiskFailurePolicy.DEFAULT;
}

Prevention

Validate env vars in deployment pipelines before JVM start
Match enum constant names exactly or verify case-insensitivity
Check enum constants for your target Cassandra version

When it happens

Trigger: Setting an env var consumed via CassandraRelevantEnv.getEnum to a value not present in the enum, e.g. JVM_TOOL_BEHAVIOR or disk-failure policy env overrides with a misspelled or unsupported value.

Common situations: Container/k8s env configuration with typos, values copied from documentation of a different Cassandra version where the enum gained/lost constants, lowercase values with toUppercase disabled.

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

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