apache/cassandra · error · ConfigurationException

Configuration must specify either node_proximity and initial

Error message

Configuration must specify either node_proximity and initial_location_provider or endpoint_snitch but not both.

What it means

Cassandra supports two ways to configure node placement: the legacy endpoint_snitch setting or the newer initial_location_provider plus node_proximity pair. applySnitch() rejects the config when both or neither form is present (hasLegacyConfig == hasModernConfig), because it cannot decide which snitch/proximity mechanism to instantiate.

Source

Thrown at src/java/org/apache/cassandra/config/DatabaseDescriptor.java:1777

            }

            for (String token : tokens)
                partitioner.getTokenFactory().validate(token);
        }
        else if (conf.num_tokens == null)
        {
            conf.num_tokens = 1;
        }
    }

    // definitely not safe for tools + clients - implicitly instantiates StorageService
    public static void applySnitch()
    {
        boolean hasLegacyConfig = conf.endpoint_snitch != null;
        boolean hasModernConfig = conf.initial_location_provider != null && conf.node_proximity != null;

        if (hasLegacyConfig == hasModernConfig)
            throw new ConfigurationException("Configuration must specify either node_proximity and " +
                                             "initial_location_provider or endpoint_snitch but not both. ");

        NodeProximity proximity;
        NodeAddressConfig addressConfig;
        if (hasLegacyConfig)
        {
            logger.info("Use of endpoint_snitch in configuration is deprecated and should be replaced by " +
                        "initial_location_provider and node_proximity");
            SnitchAdapter adapter = new SnitchAdapter(createEndpointSnitch(conf.endpoint_snitch));
            proximity = adapter;
            initialLocationProvider = adapter;
            addressConfig = adapter;
        }
        else
        {
            proximity = createProximityImpl(conf.node_proximity);
            initialLocationProvider = createInitialLocationProvider(conf.initial_location_provider);
            addressConfig = conf.addresses_config != null

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Keep only one scheme: remove endpoint_snitch and set both initial_location_provider and node_proximity, or remove both modern keys and keep endpoint_snitch
  2. If you intended the legacy snitch, add endpoint_snitch (e.g. SimpleSnitch) and delete the modern keys
  3. If you intended the modern scheme, ensure BOTH initial_location_provider and node_proximity are set — one alone still counts as no modern config

Example fix

# before (cassandra.yaml)
endpoint_snitch: SimpleSnitch
initial_location_provider: DefaultLocationProvider
node_proximity: DefaultProximity
# after (choose one)
endpoint_snitch: SimpleSnitch
# or, without the endpoint_snitch line:
initial_location_provider: DefaultLocationProvider
node_proximity: DefaultProximity
Defensive patterns

Strategy: validation

Validate before calling

if (hasLegacy == hasModern) throw new IllegalStateException("pick one snitch scheme");

Try / catch

try { DatabaseDescriptor.applySnitch(); } catch (ConfigurationException e) { /* keep one scheme */ }

Prevention

When it happens

Trigger: cassandra.yaml (or Config) has both endpoint_snitch and (initial_location_provider with node_proximity) set, or has neither; DatabaseDescriptor.applySnitch() throws ConfigurationException at startup.

Common situations: Upgrading to a version that introduced initial_location_provider/node_proximity while the old endpoint_snitch line was left in the yaml; partially migrating config where only one of the two modern keys was added; fresh installs missing any snitch configuration.

Related errors

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