apache/cassandra · error · IllegalArgumentException

Invalid value for %s: '%s' is a required keyspace property

Error message

Invalid value for %s: '%s' is a required keyspace property

What it means

Guardrails that constrain keyspace attributes (e.g. keyspace creation guardrails) validate the user-supplied property map. If the map contains a property that is a REQUIRED keyspace attribute (per KeyspaceAttributes.requiredKeywords(), like 'replication' in a relevant context), it cannot be used as a guardrail-controlled value, so an IllegalArgumentException is thrown. This prevents configuring a guardrail over something Cassandra always requires.

Source

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

        Set<String> diff = Sets.difference(lowerCaseProperties, TableAttributes.allKeywords());

        if (!diff.isEmpty())
            throw new IllegalArgumentException(invalidValueMessage(name, diff, "table"));

        return lowerCaseProperties;
    }

    private static Set<String> validateKeyspaceProperties(Set<String> properties, String name)
    {
        if (properties == null)
            throw new IllegalArgumentException(format("Invalid value for %s: null is not allowed", name));

        Set<String> lowerCaseProperties = properties.stream().map(LocalizeString::toLowerCaseLocalized).collect(toSet());

        for (String requiredKeyword : KeyspaceAttributes.requiredKeywords())
        {
            if (lowerCaseProperties.contains(requiredKeyword))
                throw new IllegalArgumentException(format("Invalid value for %s: '%s' is a required keyspace property", name, requiredKeyword));
        }

        Set<String> diff = Sets.difference(lowerCaseProperties, KeyspaceAttributes.allKeywords());

        if (!diff.isEmpty())
            throw new IllegalArgumentException(invalidValueMessage(name, diff, "keyspace"));

        return lowerCaseProperties;
    }

    public static String invalidValueMessage(String name, Set<String> invalidProperties, String type)
    {
        if (invalidProperties.size() == 1)
            return format("Invalid value for %s: '%s' does not parse as valid %s property.",
                          name, invalidProperties, type);

        return format("Invalid values for %s: '%s' do not parse as valid %s properties",
                      name, invalidProperties, type);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Remove the required keyspace property (e.g. 'replication', 'durable_writes') from the guardrail's property list in cassandra.yaml.
  2. Re-run Config validation / start the node to confirm the guardrail now validates.
  3. Only list optional keyspace attributes in the guardrail; use other guardrails/mechanisms for required attributes.

Example fix

// before (cassandra.yaml)
replication_properties_guardrail:
  disallowed_properties: [replication, read_repair]
// after
replication_properties_guardrail:
  disallowed_properties: [read_repair]
Defensive patterns

Strategy: validation

Validate before calling

Set<String> required = KeyspaceAttributes.requiredKeywords();
if (props.stream().map(String::toLowerCase).anyMatch(required::contains))
    throw new IllegalArgumentException("guardrail list must not include required keyspace properties");

Try / catch

try { config.validate(); } catch (IllegalArgumentException e) { LOG.error("guardrail config invalid: {}", e.getMessage()); throw new ConfigurationException(e); }

Prevention

When it happens

Trigger: Calling validateForbid/allow-list style guardrail configuration (e.g. setting guardrails for keyspace properties in cassandra.yaml or via Config with properties containing required keywords such as 'replication' or 'durable_writes') when the property set includes a required keyword.

Common situations: Operators adding keyspace property guardrails to cassandra.yaml and mistakenly listing 'replication' or 'durable_writes' in the guardrail's property list; copying guardrail config examples that include required keyspace attributes.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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