apache/cassandra · error · IllegalStateException

Failed to find first CMS node in directory

Error message

Failed to find first CMS node in directory

What it means

After registering the first node's addresses into the Directory, forceInitializedState() looks up the NodeId for the local broadcast address; a null result means the directory update did not produce a registered peer for the CMS seed node, which is an internal invariant failure.

Source

Thrown at src/java/org/apache/cassandra/tcm/ClusterMetadata.java:495

    public ClusterMetadata forceInitializedState(int clusterIdentifier,
                                                 NodeAddresses addresses,
                                                 NodeVersion version,
                                                 Location location)
    {
        if (this.metadataIdentifier != EMPTY_METADATA_IDENTIFIER)
            throw new IllegalStateException(String.format("Can only initialize cluster identifier once, but it was already set to %d", this.metadataIdentifier));

        if (clusterIdentifier == EMPTY_METADATA_IDENTIFIER)
            throw new IllegalArgumentException("Can not initialize cluster with empty cluster identifier");

        if (this.epoch.isAfter(Epoch.FIRST))
            throw new IllegalStateException(String.format("Can only initialize cluster identifier during epoch %d, but current epoch is %d", Epoch.FIRST.getEpoch(), epoch.getEpoch()));

        // Maybe register the first CMS node. If upgrading from gossip, this should be a no-op
        Directory withRegistered = directory.with(addresses, location, version);
        NodeId firstNode = withRegistered.peerId(addresses.broadcastAddress);
        if (firstNode == null)
            throw new IllegalStateException("Failed to find first CMS node in directory");

        CMSMembership initialCMS = cmsMembership.startJoining(firstNode).finishJoining(firstNode);
        return new ClusterMetadata(clusterIdentifier,
                                   epoch,
                                   partitioner,
                                   schema,
                                   withRegistered,
                                   tokenMap,
                                   placements,
                                   accordFastPath,
                                   lockedRanges,
                                   inProgressSequences,
                                   consensusMigrationState,
                                   extensions,
                                   accordStaleReplicas,
                                   initialCMS);
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Check cassandra.yaml broadcast_address/broadcast_and_rpc_address match the address the node registers with.
2. Confirm the node's location and version arguments passed to forceInitializedState() are correct.
3. Retry bootstrap on a clean state; if reproducible, capture the directory contents and report a bug (invariant violation).

Example fix

// before
Directory withRegistered = directory.with(addresses, location, version);
NodeId firstNode = withRegistered.peerId(addresses.broadcastAddress); // null
// after
Directory withRegistered = directory.with(addresses, location, version);
NodeId firstNode = withRegistered.peerId(addresses.broadcastAddress);
if (firstNode == null)
    throw new IllegalStateException("peerId null for " + addresses.broadcastAddress + "; check broadcast_address config");

InetAddressAndPort bc = FBUtilities.getBroadcastAddressAndPort();
if (directory.peerId(bc) == null && directory.with(addresses, location, version).peerId(bc) == null)
    throw new IllegalStateException("Broadcast address " + bc + " not registerable in directory");

try {
    cms.forceInitializedState(...);
} catch (IllegalStateException e) {
    logger.error("Directory registration failed; verify broadcast_address", e);
}

When it happens

Trigger: directory.with(addresses, location, version) returns a Directory whose peerId(addresses.broadcastAddress) is null — i.e. the local node's broadcast address does not match any registered peer after the update.

Common situations: Broadcast address misconfiguration (broadcast_address differs from the address actually registered), inconsistent node configuration during first-cluster bootstrap, or a bug/race in the directory registration path during upgrade from gossip.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Unable to create directory:
• Unable to list directory
• Unknown endpoint %s
• Can only initialize cluster identifier during epoch %d, but
• Core cluster metadata objects should be addressed directly,

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