apache/cassandra · error · ConfigurationException

Unrecognized strategy option {%s} passed to %s for keyspace

Error message

Unrecognized strategy option {%s} passed to %s for keyspace %s. Expected options: %s

What it means

Thrown by AbstractReplicationStrategy.validateExpectedOptions() when a keyspace's replication strategy options (configOptions) contain a key the strategy class does not recognize for the current cluster metadata. It names the offending option, the strategy class, the keyspace, and the set of expected options.

Source

Thrown at src/java/org/apache/cassandra/locator/AbstractReplicationStrategy.java:394

        validateExpectedOptions(snapshot);
        validateOptions();
        maybeWarnOnOptions();
        if (hasTransientReplicas() && !DatabaseDescriptor.isTransientReplicationEnabled())
        {
            throw new ConfigurationException("Transient replication is disabled. Enable in cassandra.yaml to use.");
        }
    }

    public void validateExpectedOptions(ClusterMetadata snapshot) throws ConfigurationException
    {
        Collection<String> expectedOptions = recognizedOptions(snapshot);
        if (expectedOptions == null)
            return;

        for (String key : configOptions.keySet())
        {
            if (!expectedOptions.contains(key))
                throw new ConfigurationException(String.format("Unrecognized strategy option {%s} passed to %s for keyspace %s. Expected options: %s", key, getClass().getSimpleName(), keyspaceName, expectedOptions));
        }
    }
}

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Compare the option key against the list printed in the message (Expected options) and fix the typo or remove the stale option
2. Ensure datacenter names in NetworkTopologyStrategy exactly match datacenter names reported by nodetool status
3. Use ALTER KEYSPACE to correct the replication map

Example fix

// before
CREATE KEYSPACE ks WITH replication = {'class':'NetworkTopologyStrategy','dc-1 ':3};

// after (option key must match a real DC)
CREATE KEYSPACE ks WITH replication = {'class':'NetworkTopologyStrategy','datacenter1':3};

Set<String> expected = strategy.recognizedOptions(snapshot);
for (String key : options.keySet())
    if (!expected.contains(key)) throw new IllegalArgumentException("Unknown option: " + key);

try { AbstractReplicationStrategy.validateReplicationStrategy(...); } catch (ConfigurationException e) { /* correct option keys per message */ }

When it happens

Trigger: CREATE/ALTER KEYSPACE passing a strategy_options entry (e.g. a misspelled datacenter name in NetworkTopologyStrategy, or 'replication_factor' on NetworkTopologyStrategy) that is not in recognizedOptions(snapshot); validate() calls validateExpectedOptions on every strategy validation.

Common situations: Typos in DC names that don't exist in the cluster; leftover SimpleStrategy-style 'replication_factor' option on NetworkTopologyStrategy; renamed or removed datacenters after decommissioning.

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

• default_keyspace_rf cannot be less than 1
• %s
• Invalid data rate: value must be non-negative
• Invalid data storage: %s Accepted units:%s
• default_keyspace_rf (%d) cannot be less than minimum_replica

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