apache/cassandra · error · ConfigurationException

Problem opening token allocation keyspace " + allocationKeys

Error message

Problem opening token allocation keyspace " + allocationKeyspace

What it means

BootStrapper.allocateTokens opens the keyspace whose replication is used to allocate a new node's tokens and throws ConfigurationException when Keyspace.open returns null, i.e. the named keyspace does not exist. Token allocation via TokenAllocatorFactory requires a real keyspace to compute ownership, so without it bootstrap cannot proceed. This happens only when an explicit allocation keyspace was configured (allocate_tokens_for_local_replication_factor / allocationKeyspace).

Source

Thrown at src/java/org/apache/cassandra/dht/BootStrapper.java:277

        List<Token> tokens = new ArrayList<>(initialTokens.size());
        for (String tokenString : initialTokens)
        {
            Token token = metadata.tokenMap.partitioner().getTokenFactory().fromString(tokenString);
            if (metadata.tokenMap.owner(token) != null)
                throw new ConfigurationException("Bootstrapping to existing token " + tokenString + " is not allowed (decommission/removenode the old node first).");
            tokens.add(token);
        }
        return tokens;
    }

    static Collection<Token> allocateTokens(final ClusterMetadata metadata,
                                            InetAddressAndPort address,
                                            String allocationKeyspace,
                                            int numTokens)
    {
        Keyspace ks = Keyspace.open(allocationKeyspace);
        if (ks == null)
            throw new ConfigurationException("Problem opening token allocation keyspace " + allocationKeyspace);
        AbstractReplicationStrategy rs = ks.getReplicationStrategy();

        Collection<Token> tokens = TokenAllocation.allocateTokens(metadata, rs, address, numTokens);
        BootstrapDiagnostics.tokensAllocated(address, metadata, allocationKeyspace, numTokens, tokens);
        return tokens;
    }


    static Collection<Token> allocateTokens(final ClusterMetadata metadata,
                                            InetAddressAndPort address,
                                            int rf,
                                            int numTokens)
    {
        Collection<Token> tokens = TokenAllocation.allocateTokens(metadata, rf, address, numTokens);
        BootstrapDiagnostics.tokensAllocated(address, metadata, rf, numTokens, tokens);
        return tokens;
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Create the named keyspace (or correct cassandra.yaml allocate_tokens_for_local_replication_factor / the allocationKeyspace argument to an existing keyspace) before bootstrapping.
2. Wait for schema agreement (system.schema_* / schema versions match) if the keyspace exists elsewhere in the cluster but was not yet propagated to this node.
3. Remove allocate_tokens_for_local_replication_factor to fall back to random token allocation if you don't need allocation-aware tokens.
4. Verify keyspace name spelling/case with cqlsh: DESCRIBE KEYSPACES.

Example fix

// before (cassandra.yaml)
allocate_tokens_for_local_replication_factor: 3  # keyspace 'app_ks' not created yet
// after
# create keyspace first, then bootstrap:
# CREATE KEYSPACE app_ks WITH replication = {'class':'NetworkTopologyStrategy','dc1':3};
allocate_tokens_for_local_replication_factor: 3

String ksName = allocationKeyspace;
if (Schema.instance.getKeyspaceMetadata(ksName) == null)
    throw new IllegalStateException("Keyspace '" + ksName + "' must exist before token allocation/bootstrap");

boolean allocationKeyspaceUsable(String ks) { return ks != null && Schema.instance.getKeyspaceMetadata(ks) != null; }

try {
    tokens = BootStrapper.allocateTokens(metadata, address, ks, numTokens);
} catch (ConfigurationException e) {
    logger.error("Allocation keyspace unavailable: {}", e.getMessage());
    // fall back to random tokens or abort bootstrap
}

When it happens

Trigger: Calling BootStrapper.allocateTokens(metadata, address, allocationKeyspace, numTokens) where allocationKeyspace names a keyspace that does not exist in the schema; bootstrap startup with allocate_tokens_for_local_replication_factor set to a keyspace that was never created on this node (schema not yet propagated or typo in the name).

Common situations: cassandra.yaml has allocate_tokens_for_local_replication_factor pointing to a keyspace only created by an application after startup; typo or case mismatch in the keyspace name; bootstrapping a node before the schema (auth keyspaces aside) has agreed cluster-wide; using a keyspace name from a different cluster.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• manually specified tokens override automatic allocation
• Missing replication strategy class
• num_tokens must be >= 1
• Following datacenters have active nodes and must be present
• This node was decommissioned and will not rejoin the ring un

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