apache/cassandra · error · IllegalStateException

Can't join the ring because in write_survey mode and bootstr

Error message

Can't join the ring because in write_survey mode and bootstrap hasn't completed

What it means

StorageService refuses to join the ring because the node is in write_survey mode (start_native_transport with write_survey enabled) and SystemKeyspace.bootstrapComplete() is false — the node has never finished bootstrapping, so it may not accept ring membership. Throws IllegalStateException("Cannot join the ring until bootstrap completes"); the WARN is logged first.

Source

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

                Gossiper.instance.mergeNodeToGossip(metadata.myNodeId(), metadata);
            }
        }
        else if (isSurveyMode)
        {
            // if isSurveyMode then verify the node is in the right state to join the ring
            // or that it has already done so
            if (ClusterMetadata.current().myNodeState() == JOINED)
            {
                // note: this has always been a no-op, starting a previously joined node in
                // survey mode is meaningless as bootstrapping and joining the ring is already
                // complete and a full joined node being restarted in survey mode does not prevent
                // it participating in reads. This exists only for backwards compatibilty.
                logger.info("Leaving write survey mode and joining ring at operator request");
                isSurveyMode = false;
            }
            else if (!SystemKeyspace.bootstrapComplete())
            {
                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 (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

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. If the node was only surveyed and never bootstrapped, wipe data (or use a fresh data dir), remove write_survey, and do a normal bootstrap restart.
2. If bootstrap genuinely should have completed, check system.local/system.peers for bootstrap_complete and complete the interrupted bootstrap first.
3. Set write_survey:false in cassandra.yaml and restart before joining the ring.
4. Use 'nodetool status' and logs to confirm bootstrap progress; wait for completion before joinRing().

Example fix

// before (cassandra.yaml)
auto_bootstrap: true
# node never completed bootstrap, write_survey: true, joinRing called
// after
default: remove write_survey: true from cassandra.yaml, wipe data dir, restart to bootstrap normally

// before joinRing()
boolean ok = !isSurveyMode() || SystemKeyspace.bootstrapComplete();
if (!ok) throw new IllegalStateException("Complete bootstrap (or re-bootstrap without write_survey) first");

try { storageService.joinRing(); }
catch (IllegalStateException e) { /* write_survey + incomplete bootstrap: rebootstrap node */ }

When it happens

Trigger: Operator calls joinRing() (leave survey mode) on a write_survey node whose bootstrap never completed — typically the node was started with write_survey:true, never fully joined, and someone then requests joinRing().

Common situations: Write_survey mode intended only for evaluating write load without serving reads; operator forgets the node was never bootstrapped and tries to promote it; config flip of write_survey in cassandra.yaml then immediate joinRing.

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

• Not starting client transports in write_survey mode as it's
• 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 bootstrap hasn't completed.

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