{"record":{"id":"7f83c3476748d2c8","repo":"apache/cassandra","slug":"a-node-with-address-s-already-exists-cancelling","errorCode":null,"errorMessage":"A node with address %s already exists, cancelling join. Use cassandra.replace_address if you want to replace this node.","messagePattern":"A node with address (.+?) already exists, cancelling join\\. Use cassandra\\.replace_address if you want to replace this node\\.","errorType":"exception","errorClass":"java.lang.IllegalStateException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/tcm/transformations/Register.java","lineNumber":152,"sourceCode":"    {\n        return register(nodeAddresses, DatabaseDescriptor.getLocator().local(), nodeVersion);\n    }\n\n    private static NodeId register(NodeAddresses nodeAddresses, Location location, NodeVersion nodeVersion)\n    {\n        ClusterMetadata metadata = ClusterMetadata.current();\n        DatabaseDescriptor.getInitialLocationProvider().validate(metadata);\n        NodeId nodeId = metadata.directory.peerId(nodeAddresses.broadcastAddress);\n        if (nodeId == null || metadata.directory.peerState(nodeId) == NodeState.LEFT)\n        {\n            if (nodeId != null)\n                ClusterMetadataService.instance().commit(new Unregister(nodeId, EnumSet.of(NodeState.LEFT), ClusterMetadataService.instance().placementProvider()));\n            Register registration = new Register(nodeAddresses, location, nodeVersion);\n            nodeId = ClusterMetadataService.instance().commit(registration).directory.peerId(nodeAddresses.broadcastAddress);\n        }\n        else\n        {\n            throw new IllegalStateException(String.format(\"A node with address %s already exists, cancelling join. Use cassandra.replace_address if you want to replace this node.\", nodeAddresses.broadcastAddress));\n        }\n\n        logger.info(\"Registered with endpoint {}, node id: {}\", nodeAddresses.broadcastAddress, nodeId);\n        return nodeId;\n    }\n\n    private static NodeId register(boolean force)\n    {\n        // Try to recover node ID from the system keyspace\n        UUID localHostId = SystemKeyspace.getLocalHostId();\n        Directory directory = ClusterMetadata.current().directory;\n        if (force || localHostId == null)\n        {\n            NodeId nodeId = register(NodeAddresses.current());\n            localHostId = nodeId.toUUID();\n            SystemKeyspace.setLocalHostId(localHostId);\n            logger.info(\"New node ID obtained {}, (Note: This should happen exactly once per node)\", localHostId);\n            return nodeId;","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/tcm/transformations/Register.java#L134-L170","documentation":"Thrown during Register.register() when the broadcast address the node is joining with already maps to an existing peer in cluster metadata, and the node is not configured to replace that node. CMS refuses to register a duplicate address to keep the directory consistent.","triggerScenarios":"Calling register() where directory.peerId(broadcastAddress) is non-null but the node is not doing an explicit replacement (no cassandra.replace_address / replace_node configured).","commonSituations":"Cloning a VM/image with the same IP as an existing node; a previously replaced node's old entry still in metadata; accidental reuse of an assigned IP; starting a second node with a misconfigured broadcast_address.","solutions":["Set cassandra.replace_address (or replace_node) to indicate intentional replacement of the existing node","Give the new node a unique broadcast_address/port not present in the cluster","If the old node is dead, remove it from the cluster (nodetool decommission/removenode) before reusing the address","Verify with nodetool status that no live/registered node holds that IP"],"exampleFix":"// before\ncassandra.broadcast_address=10.0.0.7 // already used by node2\n// after\ncassandra.broadcast_address=10.0.0.9 // unused address\n// or, for intentional replacement:\n-Dcassandra.replace_address=10.0.0.7","handlingStrategy":"validation","validationCode":"// before starting a node, check the address is free\nboolean taken = ClusterMetadata.current().directory.peerId(broadcastAddress) != null;\nif (taken && !isReplacementConfigured()) throw new IllegalStateException(\"address in use; set replace_address or pick a new IP\");","typeGuard":null,"tryCatchPattern":"try { CMS.commit(registration); } catch (IllegalStateException e) { if (e.getMessage().contains(\"already exists\")) { /* resolve duplicate address or set replace_address */ } else throw e; }","preventionTips":["Run `nodetool status` before assigning IPs to new nodes","Never clone node images with the same broadcast_address","Decommission dead nodes before reusing their addresses"],"tags":["cluster-membership","duplicate-address","bootstrap"],"backgroundTag":"address-already-in-use","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"}