{"record":{"id":"537178bcb3423abf","repo":"apache/cassandra","slug":"token-allocation-failed-the-number-of-racks-d-in","errorCode":null,"errorMessage":"Token allocation failed: the number of racks %d in datacenter %s is lower than its replication factor %d.","messagePattern":"Token allocation failed: the number of racks (.+?) in datacenter (.+?) is lower than its replication factor (.+?)\\.","errorType":"exception","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/dht/tokenallocator/TokenAllocation.java","lineNumber":299,"sourceCode":"            // each node is treated as separate and replicates once\n            return createStrategy(locator, dc, null, 1, false);\n        }\n        else if (racks == replicas)\n        {\n            // each node is treated as separate and replicates once, with separate allocation rings for each rack\n            return createStrategy(locator, dc, rack, 1, false);\n        }\n        else if (racks > replicas)\n        {\n            // group by rack\n            return createStrategy(locator, dc, null, replicas, true);\n        }\n        else if (racks == 1)\n        {\n            return createStrategy(locator, dc, null, replicas, false);\n        }\n\n        throw new ConfigurationException(String.format(\"Token allocation failed: the number of racks %d in datacenter %s is lower than its replication factor %d.\",\n                                                       racks, dc, replicas));\n    }\n\n    // a null dc will always return true for inAllocationRing(..)\n    // a null rack will return true for inAllocationRing(..) for all nodes in the same dc\n    private StrategyAdapter createStrategy(Supplier<Locator> locator, String dc, String rack, int replicas, boolean groupByRack)\n    {\n        return new StrategyAdapter()\n        {\n            @Override\n            public int replicas()\n            {\n                return replicas;\n            }\n\n            @Override\n            public Object getGroup(InetAddressAndPort unit)\n            {","sourceCodeStart":281,"sourceCodeEnd":317,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/dht/tokenallocator/TokenAllocation.java#L281-L317","documentation":"In TokenAllocation.createStrategy, when a datacenter has more than one rack but fewer racks than the replication factor, the allocator cannot satisfy rack-aware replica placement, so it throws ConfigurationException. The replication factor must be <= the number of racks (or the DC must have exactly 1 rack with appropriate handling).","triggerScenarios":"Calling allocate for a keyspace using NetworkTopologyStrategy whose replication factor for a DC exceeds that DC's rack count (with racks > 1).","commonSituations":"NetworkTopologyStrategy configured with replication_factor 3 in a DC with only 2 racks; misconfigured cassandra-rackdc.properties so nodes report wrong racks; adding racks after strategy change.","solutions":["Increase replication factor to <= number of racks, or add more racks and distribute nodes","If single-rack semantics are acceptable, consolidate to one rack or accept rack-grouping behavior and set the replication factor to the actual rack count","Check nodetool status output to verify node DC/rack assignments match expectations","Fix rack configuration in cassandra-rackdc.properties and restart nodes before allocation"],"exampleFix":"// before\nALTER KEYSPACE ks WITH replication = {'class':'NetworkTopologyStrategy','dc1':3}; // dc1 has only 2 racks\n// after\nALTER KEYSPACE ks WITH replication = {'class':'NetworkTopologyStrategy','dc1':2}; // matches rack count","handlingStrategy":"validation","validationCode":"// replication factor must be <= number of racks in each DC\nMap<String,Integer> racksPerDc = collectRacksPerDc(); // from snitch metadata\nracksPerDc.forEach((dc, racks) -> {\n    int rf = strategy.getReplicationFactor(dc);\n    if (rf > racks) throw new IllegalArgumentException(\n        String.format(\"RF %d > racks %d in %s\", rf, racks, dc));\n});","typeGuard":null,"tryCatchPattern":"try {\n    TokenAllocation.allocate(metadata, ks, dc);\n} catch (ConfigurationException e) {\n    if (e.getMessage().contains(\"number of racks\")) {\n        // lower RF or add racks, then retry\n    }\n}","preventionTips":["Keep replication factor <= rack count per DC in NetworkTopologyStrategy","Verify cassandra-rackdc.properties assigns racks correctly on all nodes","Check nodetool status DC/rack columns after any topology change"],"tags":["token-allocation","replication-factor","racks"],"backgroundTag":"invalid-config-value","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}