apache/cassandra · error · ConfigurationException

replication_factor should not appear as an option at constru

Error message

replication_factor should not appear as an option at construction time for NetworkTopologyStrategy

What it means

NetworkTopologyStrategy assigns replication per datacenter, so a single global replication_factor option is meaningless. prepareOptions normally strips/transforms replication_factor into per-DC entries; if one still reaches the constructor, this ConfigurationException fires because the schema/creation path bypassed the transformation.

Source

Thrown at src/java/org/apache/cassandra/locator/NetworkTopologyStrategy.java:95

    private final Map<String, ReplicationFactor> datacenters;
    private final ReplicationFactor aggregateRf;
    private static final Logger logger = LoggerFactory.getLogger(NetworkTopologyStrategy.class);

    public NetworkTopologyStrategy(String keyspaceName, Map<String, String> configOptions) throws ConfigurationException
    {
        super(keyspaceName, configOptions);

        int replicas = 0;
        int trans = 0;
        Map<String, ReplicationFactor> newDatacenters = new HashMap<>();
        if (configOptions != null)
        {
            for (Entry<String, String> entry : configOptions.entrySet())
            {
                String dc = entry.getKey();
                // prepareOptions should have transformed any "replication_factor" options by now
                if (dc.equalsIgnoreCase(REPLICATION_FACTOR))
                    throw new ConfigurationException(REPLICATION_FACTOR + " should not appear as an option at construction time for NetworkTopologyStrategy");
                ReplicationFactor rf = ReplicationFactor.fromString(entry.getValue());
                replicas += rf.allReplicas;
                trans += rf.transientReplicas();
                newDatacenters.put(dc, rf);
            }
        }

        datacenters = Collections.unmodifiableMap(newDatacenters);
        aggregateRf = ReplicationFactor.withTransient(replicas, trans);
    }

    /**
     * Endpoint adder applying the replication rules for a given DC.
     */
    private static final class DatacenterEndpoints
    {
        /** List accepted endpoints get pushed into. */
        EndpointsForRange.Builder replicas;

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Replace replication_factor with explicit per-DC options: {'class':'NetworkTopologyStrategy','dc1':'3','dc2':'2'}
2. Fix the calling code so prepareOptions() runs before constructing NetworkTopologyStrategy
3. Use system_schema keyspace description to inspect and ALTER the keyspace replication settings correctly
4. If a default-per-DC factor is wanted, generate explicit per-DC values in tooling rather than passing replication_factor

Example fix

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

Map<String,String> opts = replicationOptions;
if ("NetworkTopologyStrategy".equals(opts.get("class")) && opts.containsKey("replication_factor")) throw new IllegalArgumentException("Use per-DC replication options instead of replication_factor");

try { session.execute(createKs); }
catch (InvalidQueryException e) { /* fix replication map: drop replication_factor */ }

When it happens

Trigger: CREATE KEYSPACE ... WITH replication = {'class':'NetworkTopologyStrategy','replication_factor':3} — replication_factor appears in configOptions at construction time, meaning prepareOptions did not remove it (e.g. direct constructor use or altered options map).

Common situations: Users porting SimpleStrategy configs to NetworkTopologyStrategy without converting replication_factor into per-DC options; tooling/migration scripts building strategy options programmatically; drivers or ORMs generating invalid replication maps.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• Configuration for at least one datacenter must be present
• Can not alter a keyspace to use MetaReplicationStrategy
• category %s not found in %s
• 'Get CIDR groups for IP' operation not supported by %s
• ACCESS TO DATACENTERS operations not supported by AllowAllNe

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