apache/cassandra · error · IllegalStateException

Can't join the ring because bootstrap hasn't completed.

Error message

Can't join the ring because bootstrap hasn't completed.

What it means

StorageService rejects joining the ring when isBootstrapMode() is true — the node is configured to bootstrap but bootstrap has not completed yet, so ring membership cannot be assumed. Logs a WARN and throws IllegalStateException("Cannot join the ring until bootstrap completes").

Source

Thrown at src/java/org/apache/cassandra/service/StorageService.java:1026

                throw new IllegalStateException("Cannot join the ring until bootstrap completes");
            }
            else if (readyToFinishJoiningRing())
            {
                logger.info("Leaving write survey mode and joining ring at operator request");
                exitWriteSurveyMode();
                isSurveyMode = false;
                daemon.start();
            }
            else
            {
                logger.warn("Can't join the ring because in write_survey mode and bootstrap hasn't completed");
                throw new IllegalStateException("Cannot join the ring until bootstrap completes");
            }
        }
        else if (isBootstrapMode())
        {
            // bootstrap is not complete hence node cannot join the ring
            logger.warn("Can't join the ring because bootstrap hasn't completed.");
            throw new IllegalStateException("Cannot join the ring until bootstrap completes");
        }
    }

    public void resumeBootstrapSequence()
    {
        ClusterMetadata metadata = ClusterMetadata.current();
        NodeId id = metadata.myNodeId();
        MultiStepOperation<?> sequence = metadata.inProgressSequences.get(id);

        if (!(sequence instanceof BootstrapAndJoin) && !(sequence instanceof BootstrapAndReplace))
            throw new IllegalStateException("Can not resume bootstrap as join sequence has not been started");
        clearOngoingBootstrap();
        InProgressSequences.finishInProgressSequences(id);
        // only start transports and report that we're done if the resumed bootstrap completed successfully
        // See CASSANDRA-16491
        if (ongoingBootstrap.get() == null)
        {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Wait for bootstrap to finish: monitor 'nodetool netstats' until streaming completes and the node reports UP/NORMAL.
2. If bootstrap is stalled, diagnose the source node/network (netstats logs) or restart the node to resume bootstrap.
3. Only call joinRing() after bootstrap_complete is true in system.local.
4. If the node should not bootstrap at all, set auto_bootstrap:false deliberately and understand the implications.

Example fix

// before
nodetool joinring  # called while bootstrap streaming still in progress
// after
nodetool netstats   # wait until no active streaming
nodetool joinring

// wait for bootstrap before joining
if (storageService.isBootstrapMode()) {
    // poll nodetool netstats / bootstrap_complete before joinRing()
}

try { storageService.joinRing(); }
catch (IllegalStateException e) { log.warn("bootstrap still in progress; retry later", e); }

When it happens

Trigger: joinRing() called on a node currently in bootstrap mode (first startup / streaming still in progress) — e.g. operator runs nodetool joinring (or JMX equivalent) while initial bootstrap streaming is still underway.

Common situations: Impatient operators during first bootstraps of nodes with large data; bootstrap stalled due to slow streaming or a failed peer; automation scripts that call joinRing too early after restart.

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

• Can not resume bootstrap as join sequence has not been start
• Can not finish joining ring as join sequence has not been st
• Can not finish joining ring, sequence is in an incorrect sta
• Can't join the ring because in write_survey mode and bootstr
• %s function resource has no function name

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