apache/cassandra · error · java.lang.IllegalStateException

Tried to replace same address, but node does not seem to be…

Error message

Tried to replace same address, but node does not seem to be registered

What it means

Thrown by ClusterMetadataService.maybeRegister() when the node is configured to replace an existing node at the same broadcast address (cassandra.replace_address pointing at itself), but this node has no NodeId in the current cluster metadata directory. Registration exists to hand out a NodeId; replacement requires the node to already be a registered member whose identity can be reused.

Solutions

Remove cassandra.replace_address (the address is free; do a normal bootstrap/register instead)
If replacement is intended, ensure the old node is still registered in CMS (verify with nodetool status / cms show); re-register it or restore cluster metadata
Wipe stale system.local host id and data directories, then start as a fresh node

Example fix

// before: cassandra.yaml
auto_bootstrap: true
replace_address: 10.0.0.5  // same as this node, already unregistered
// after
auto_bootstrap: true
// remove replace_address and let the node register normally

Defensive patterns

Strategy: validation

Validate before calling

// before starting with replacement
NodeId self = ClusterMetadata.current().myNodeId();
if (isReplacingSameAddress() && self == NodeId.UNREGISTERED) {
    // the node is not registered; do a normal register instead of replace
}

Prevention

Only set replace_address when the target node is still registered in cluster metadata
Use replace_node with an explicit host id instead of replace_address self-replacement
Wipe data dirs when the old node was already removed from CMS

When it happens

Trigger: Calling maybeRegister() when isReplacingSameAddress() is true and ClusterMetadata.current().myNodeId() returns NodeId.UNREGISTERED — i.e. the local node is not present in the CMS directory under the current address.

Common situations: Starting a node with cassandra.replace_address equal to its own address after the old node was fully removed (unregistered) from cluster metadata; stale data dirs left behind while metadata was reset; attempting replacement before the node ever joined.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/tcm/transformations/Register.java:113

        for (Map.Entry<NodeId, NodeAddresses> entry : prev.directory.addresses.entrySet())
        {
            NodeAddresses existingAddresses = entry.getValue();
            if (addresses.conflictsWith(existingAddresses))
                return new Rejected(INVALID, String.format("New addresses %s conflicts with existing node %s with addresses %s", addresses, entry.getKey(), existingAddresses));
        }

        ClusterMetadata.Transformer next = prev.transformer()
                                               .register(addresses, location, version);
        return Transformation.success(next, LockedRanges.AffectedRanges.EMPTY);
    }

    public static NodeId maybeRegister()
    {
        if (isReplacingSameAddress())
        {
            NodeId self = ClusterMetadata.current().myNodeId();
            if (self == NodeId.UNREGISTERED)
                throw new IllegalStateException("Tried to replace same address, but node does not seem to be registered");

            return self;
        }
        return register(false);
    }

    @VisibleForTesting
    public static NodeId register(NodeAddresses nodeAddresses)
    {
        return register(nodeAddresses, NodeVersion.CURRENT);
    }

    @VisibleForTesting
    public static NodeId register(NodeAddresses nodeAddresses, Location location)
    {
        return register(nodeAddresses, location, NodeVersion.CURRENT);
    }

View on GitHub (pinned to 88fd0f6a0e)