apache/cassandra · error · IllegalStateException

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

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.

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

• Can not finish joining ring as join sequence has not been…
• Can not finish joining ring, sequence is in an incorrect…
• Can not resume bootstrap as join sequence has not been…
• Can't join the ring because bootstrap hasn't completed.
• Not starting client transports in write_survey mode as it's…

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

Appendix: 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)