apache/cassandra · error · ConfigurationException

This ec2-enabled location provider appears to be using the

Error message

This ec2-enabled location provider appears to be using the %s naming scheme for regions, but existing nodes in cluster are using the opposite: region(s) = %s, availability zone(s) = %s. Please check the %s property in the %s configuration file for more details.

What it means

Ec2LocationProvider.validate cross-checks the region/AZ naming scheme the node derived from EC2 metadata (legacy names like us-east-1 vs the standard DNS-suffix scheme) against what existing cluster nodes report. If the schemes conflict it throws ConfigurationException, preventing a node from joining with inconsistent dc/rack naming.

Solutions

  1. Set ec2_naming_scheme in cassandra.yaml to match the existing cluster (legacy or standard)
  2. Align every node's cassandra-rackdc.properties dc/rack values with the chosen scheme
  3. During migration, update nodes one DC at a time so all nodes use the same naming scheme
  4. If names were customized, switch to GossipingPropertyFileSnitch instead of Ec2Snitch

Example fix

// before (cassandra.yaml)
endpoint_snitch: Ec2Snitch
// after
endpoint_snitch: Ec2Snitch
ec2_naming_scheme: legacy
Defensive patterns

Strategy: validation

Validate before calling

Set<String> dcs = StorageService.instance.getTokenMetadata().getAllDatacenters();
String myDc = /* from ec2 metadata */;
if (!dcs.isEmpty() && !dcs.contains(myDc)) throw new IllegalStateException("naming scheme mismatch with cluster dcs: " + dcs);

Try / catch

try { node.start(); }
catch (ConfigurationException e) { logger.error("EC2 naming scheme mismatch: {}", e.getMessage()); System.exit(1); }

Prevention

When it happens

Trigger: Node starts with ec2_naming_scheme (or derived default) set to one scheme while gossip/cluster metadata shows other nodes' datacenters and racks using the opposite scheme; validate() finds no matching region among the cluster's datacenters.

Common situations: Mixed-version cluster after migration from legacy EC2 region naming (pre-4.0) to the new scheme; cloned AMIs with stale cassandra-rackdc.properties; manually edited dc names in cassandra-rackdc.properties not matching the snitch's scheme.

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

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

Appendix: source

Thrown at src/java/org/apache/cassandra/locator/Ec2LocationProvider.java:151

        }

        for (String rack : racks)
        {
            // predicated on late-2017 AWS naming 'convention' that AZs do not have a digit as the first char -
            // we had that in our legacy AZ (rack) names. Thus we test to see if the rack is in the legacy format.
            //
            // NOTE: the allowed custom suffix only applies to datacenter (region) names, not availability zones.
            boolean rackUsesLegacyFormat = rack.matches("[\\d][a-z]");
            if (rackUsesLegacyFormat != usingLegacyNaming)
            {
                valid = false;
                break;
            }
        }

        if (!valid)
        {
            throw new ConfigurationException(String.format("This ec2-enabled location provider appears to be using the " +
                                                           "%s naming scheme for regions, but existing nodes in cluster " +
                                                           "are using the opposite: " +
                                                           "region(s) = %s, availability zone(s) = %s. " +
                                                           "Please check the %s property in the %s configuration file " +
                                                           "for more details.",
                                                           usingLegacyNaming ? "legacy" : "standard", datacenters, racks,
                                                           SNITCH_PROP_NAMING_SCHEME, SnitchProperties.RACKDC_PROPERTY_FILENAME));
        }
        return true;
    }
}

View on GitHub (pinned to 88fd0f6a0e)