apache/cassandra · error · ConfigurationException

SimpleStrategy requires a replication_factor strategy…

Error message

SimpleStrategy requires a replication_factor strategy option.

What it means

SimpleStrategy places replicas with a single flat replication_factor and therefore requires exactly that option in the replication map. validateOptionsInternal throws this ConfigurationException when the 'replication_factor' key is absent, because the strategy cannot determine how many replicas to place.

Solutions

1. Add the replication_factor option: {'class':'SimpleStrategy','replication_factor':3}
2. Re-run the CREATE/ALTER KEYSPACE statement with the corrected replication map
3. If multi-DC is intended, switch to NetworkTopologyStrategy with per-DC factors instead

Example fix

// before
CREATE KEYSPACE ks WITH replication = {'class':'SimpleStrategy'};
// after
CREATE KEYSPACE ks WITH replication = {'class':'SimpleStrategy','replication_factor':3};

if ("SimpleStrategy".equals(opts.get("class")) && !opts.containsKey("replication_factor"))
    throw new IllegalArgumentException("SimpleStrategy requires a replication_factor option");

try { session.execute(createKeyspaceCql); }
catch (InvalidQueryException e) { if (e.getMessage().contains("requires a replication_factor")) { /* append replication_factor and retry */ } }

When it happens

Trigger: CREATE/ALTER KEYSPACE ... replication = {'class':'SimpleStrategy'} (or with no 'replication_factor' key) submitted via cqlsh, driver schema metadata, or programmatic KeyspaceMetadata construction.

Common situations: Copy-pasting NetworkTopologyStrategy-style per-DC options with SimpleStrategy; drivers generating schema without replication_factor; hand-edited migration scripts; restoring schema dumps that dropped the option.

Understand the failure class

Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.

Related errors

• Cannot alter RF while some endpoints are not in normal…
• default_keyspace_rf cannot be less than 1
• default_keyspace_rf ( ) cannot be less than…
• default_keyspace_rf to be set
• default_keyspace_rf to be set

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

Appendix: source

Thrown at src/java/org/apache/cassandra/locator/SimpleStrategy.java:128

            InetAddressAndPort ep = endpoints.endpoint(owner);
            if (!replicas.endpoints().contains(ep))
                replicas.add(new Replica(ep, replicaRange, replicas.size() < rf.fullReplicas));
        }

        return replicas.build();
    }


    @Override
    public ReplicationFactor getReplicationFactor()
    {
        return rf;
    }

    private static void validateOptionsInternal(Map<String, String> configOptions) throws ConfigurationException
    {
        if (configOptions.get(REPLICATION_FACTOR) == null)
            throw new ConfigurationException("SimpleStrategy requires a replication_factor strategy option.");
    }

    @Override
    public void validateOptions() throws ConfigurationException
    {
        validateOptionsInternal(configOptions);
        validateReplicationFactor(configOptions.get(REPLICATION_FACTOR));
    }

    @Override
    public void maybeWarnOnOptions(ClientState state)
    {
        if (!SchemaConstants.isSystemKeyspace(keyspaceName))
        {
            int nodeCount = StorageService.instance.getHostIdToEndpoint().size();
            // nodeCount==0 on many tests
            Guardrails.minimumReplicationFactor.guard(rf.fullReplicas, keyspaceName, false, state);
            Guardrails.maximumReplicationFactor.guard(rf.fullReplicas, keyspaceName, false, state);

View on GitHub (pinned to 88fd0f6a0e)