apache/cassandra · error · ConfigurationException

Configuration for at least one datacenter must be present

Error message

Configuration for at least one datacenter must be present

What it means

NetworkTopologyStrategy requires at least one datacenter option because replication is defined per DC. validateExpectedOptions rejects an empty options map with this ConfigurationException, so a keyspace cannot be created/validated with zero datacenter configuration.

Source

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

                           .forEach(e -> options.putIfAbsent(e.getKey(), e.getValue()));
        }

        if (replication != null) {
            ReplicationFactor defaultReplicas = ReplicationFactor.fromString(replication);
            Datacenters.getValidDatacenters(ClusterMetadata.current())
                       .forEach(dc -> options.putIfAbsent(dc, defaultReplicas.toParseableString()));
        }

        options.values().removeAll(Collections.singleton("0"));
    }

    @Override
    public void validateExpectedOptions(ClusterMetadata metadata) throws ConfigurationException
    {
        // Do not accept query with no data centers specified.
        if (this.configOptions.isEmpty())
        {
            throw new ConfigurationException("Configuration for at least one datacenter must be present");
        }

        // Validate the data center names
        super.validateExpectedOptions(metadata);

        if (keyspaceName.equalsIgnoreCase(SchemaConstants.AUTH_KEYSPACE_NAME))
        {
            Set<String> differenceSet = Sets.difference(metadata.directory.knownDatacenters(), configOptions.keySet());
            if (!differenceSet.isEmpty())
            {
                throw new ConfigurationException("Following datacenters have active nodes and must be present in replication options for keyspace " + SchemaConstants.AUTH_KEYSPACE_NAME + ": " + differenceSet.toString());
            }
        }
        logger.info("Configured datacenter replicas are {}", FBUtilities.toString(datacenters));
    }

    @Override
    public void validateOptions() throws ConfigurationException

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Add at least one datacenter with its replication factor: {'class':'NetworkTopologyStrategy','dc1':'3'}
2. List datacenters via SELECT * FROM system.local (or nodetool status) to get correct DC names
3. Fix templating/tooling so the DC options collection is non-empty before rendering the CREATE statement
4. Use SimpleStrategy temporarily only for single-node dev clusters, not production

Example fix

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

Map<String,String> opts = replicationOptions;
if ("NetworkTopologyStrategy".equals(opts.getOrDefault("class","")) && opts.size() <= 1) throw new IllegalArgumentException("Specify at least one datacenter with replication factor");

try { session.execute(createKs); }
catch (InvalidQueryException e) { /* add per-DC options and retry */ }

When it happens

Trigger: validateExpectedOptions is invoked (keyspace creation/alter or query validation) and this.configOptions is empty — e.g. replication = {'class':'NetworkTopologyStrategy'} with no DC entries.

Common situations: CREATE KEYSPACE statement with the strategy class but no DC arguments; ALTER TABLE dropping all DC options; templating tools rendering an empty DC list; drivers building the replication map dynamically from an empty collection.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• replication_factor should not appear as an option at constru
• Cannot use keyspace inheriting fast path strategy with keysp
• Cannot set %s to empty string
• Can not alter a keyspace to use MetaReplicationStrategy
• Cannot add new field %s of type %s to user type %s as it wou

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