{"record":{"id":"eea55e3801fe1f99","repo":"apache/cassandra","slug":"cannot-join-the-ring-until-bootstrap-completes","errorCode":null,"errorMessage":"Cannot join the ring until bootstrap completes","messagePattern":"Cannot join the ring until bootstrap completes","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/service/StorageService.java","lineNumber":1008,"sourceCode":"            }\n        }\n        else if (isSurveyMode)\n        {\n            // if isSurveyMode then verify the node is in the right state to join the ring\n            // or that it has already done so\n            if (ClusterMetadata.current().myNodeState() == JOINED)\n            {\n                // note: this has always been a no-op, starting a previously joined node in\n                // survey mode is meaningless as bootstrapping and joining the ring is already\n                // complete and a full joined node being restarted in survey mode does not prevent\n                // it participating in reads. This exists only for backwards compatibilty.\n                logger.info(\"Leaving write survey mode and joining ring at operator request\");\n                isSurveyMode = false;\n            }\n            else if (!SystemKeyspace.bootstrapComplete())\n            {\n                logger.warn(\"Can't join the ring because in write_survey mode and bootstrap hasn't completed\");\n                throw new IllegalStateException(\"Cannot join the ring until bootstrap completes\");\n            }\n            else if (readyToFinishJoiningRing())\n            {\n                logger.info(\"Leaving write survey mode and joining ring at operator request\");\n                exitWriteSurveyMode();\n                isSurveyMode = false;\n                daemon.start();\n            }\n            else\n            {\n                logger.warn(\"Can't join the ring because in write_survey mode and bootstrap hasn't completed\");\n                throw new IllegalStateException(\"Cannot join the ring until bootstrap completes\");\n            }\n        }\n        else if (isBootstrapMode())\n        {\n            // bootstrap is not complete hence node cannot join the ring\n            logger.warn(\"Can't join the ring because bootstrap hasn't completed.\");","sourceCodeStart":990,"sourceCodeEnd":1026,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/service/StorageService.java#L990-L1026","documentation":"A node started in write_survey mode (join_ring=false with bootstrap) collects writes without owning token ranges. joinRing() from this mode is only allowed once bootstrap has completed; otherwise an IllegalStateException is thrown because the node cannot safely take ownership of its range yet.","triggerScenarios":"Calling StorageService.joinRing() (JMX or API) while isSurveyMode is true and SystemKeyspace.bootstrapComplete() is false.","commonSituations":"Operator starting a node with -Dcassandra.join_ring=false then calling joinRing before streaming/bootstrap finished; automation that joins the ring too early.","solutions":["Wait for bootstrap to complete (watch `nodetool netstats` / bootstrap logs) before calling joinRing","Verify SystemKeyspace.bootstrapComplete() is true before invoking joinRing","If the node is stuck, fix the failing bootstrap (streaming errors) and retry","Restart the node normally if bootstrap was never intended"],"exampleFix":"// before\nss.joinRing();\n// after\nif (SystemKeyspace.bootstrapComplete())\n    ss.joinRing();","handlingStrategy":"validation","validationCode":"if (!SystemKeyspace.bootstrapComplete()) skipJoinRing();","typeGuard":null,"tryCatchPattern":"try { ss.joinRing(); } catch (IllegalStateException e) { /* wait for bootstrap, retry later */ }","preventionTips":["Wait for bootstrap completion before joinRing in write-survey mode","Monitor nodetool netstats for streaming progress","Automate join only on bootstrap-complete signal"],"tags":["bootstrap","join","write-survey"],"backgroundTag":"invalid-state-transition","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"}