apache/cassandra · critical · RuntimeException

Error during joining the ring

Error message

Error during joining the ring

What it means

Join calls StorageServiceMBean.joinRing() to make the node join the ring; if that remote call fails with IOException the command wraps it in RuntimeException('Error during joining the ring'). Common causes are the node not being ready, bootstrap failures, or communication problems with the local JMX endpoint.

Solutions

1. Check node logs for the underlying bootstrap/streaming exception
2. Verify seeds are reachable and inter-node ports (7000/7001, storage_port) are open
3. Confirm node state (nodetool status) — it must be in a joinable state (not already joined, not decommissioned)
4. After fixing, retry nodetool join

Example fix

// before
probe.joinRing(); // throws IOException -> 'Error during joining the ring'
// after
// fix underlying issue first (seeds/ports/disk), then:
try { probe.joinRing(); } catch (IOException e) { check logs for root cause; }

// verify node is in a joinable state before joining
boolean joined = probe.isJoined();
if (joined) throw new IllegalStateException("node already joined");

try { nodetoolJoin(); } catch (RuntimeException e) { if (e.getMessage().equals("Error during joining the ring")) { /* inspect node logs for bootstrap failure */ } }

When it happens

Trigger: Running `nodetool join` (or a wrapper executing execute()) when the node cannot bootstrap: IO errors during streaming, node still decommissioned/in wrong state, or the local JMX call failing.

Common situations: Node restarted after decommission; bootstrap blocked by insufficient disk or seed connectivity; firewalled inter-node ports; attempting join on an already-failing node.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• throw new IOException(e)
• Unable to pre-initialize distributed metadata log table
• A node required to move the data consistently is down
• A node with address already exists, cancelling join. Use…
• Attempted skipBytes() on a closed RAR

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

Appendix: source

Thrown at src/java/org/apache/cassandra/tools/nodetool/Join.java:41

import picocli.CommandLine.Command;

import static com.google.common.base.Preconditions.checkState;


@Command(name = "join", description = "Join the ring")
public class Join extends AbstractCommand
{
    @Override
    public void execute(NodeProbe probe)
    {
        checkState(!probe.isJoined(), "This node has already joined the ring.");
        try
        {
            probe.joinRing();
        } catch (IOException e)
        {
            throw new RuntimeException("Error during joining the ring", e);
        }
    }
}

View on GitHub (pinned to 88fd0f6a0e)