{"record":{"id":"5cb7f4ff134f6551","repo":"apache/cassandra","slug":"can-t-join-the-ring-because-bootstrap-hasn-t-compl","errorCode":null,"errorMessage":"Can't join the ring because bootstrap hasn't completed.","messagePattern":"Can't join the ring because bootstrap hasn't completed\\.","errorType":"console","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/service/StorageService.java","lineNumber":1026,"sourceCode":"                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.\");\n            throw new IllegalStateException(\"Cannot join the ring until bootstrap completes\");\n        }\n    }\n\n    public void resumeBootstrapSequence()\n    {\n        ClusterMetadata metadata = ClusterMetadata.current();\n        NodeId id = metadata.myNodeId();\n        MultiStepOperation<?> sequence = metadata.inProgressSequences.get(id);\n\n        if (!(sequence instanceof BootstrapAndJoin) && !(sequence instanceof BootstrapAndReplace))\n            throw new IllegalStateException(\"Can not resume bootstrap as join sequence has not been started\");\n        clearOngoingBootstrap();\n        InProgressSequences.finishInProgressSequences(id);\n        // only start transports and report that we're done if the resumed bootstrap completed successfully\n        // See CASSANDRA-16491\n        if (ongoingBootstrap.get() == null)\n        {","sourceCodeStart":1008,"sourceCodeEnd":1044,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/service/StorageService.java#L1008-L1044","documentation":"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\").","triggerScenarios":"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.","commonSituations":"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.","solutions":["Wait for bootstrap to finish: monitor 'nodetool netstats' until streaming completes and the node reports UP/NORMAL.","If bootstrap is stalled, diagnose the source node/network (netstats logs) or restart the node to resume bootstrap.","Only call joinRing() after bootstrap_complete is true in system.local.","If the node should not bootstrap at all, set auto_bootstrap:false deliberately and understand the implications."],"exampleFix":"// before\nnodetool joinring  # called while bootstrap streaming still in progress\n// after\nnodetool netstats   # wait until no active streaming\nnodetool joinring","handlingStrategy":"validation","validationCode":"// wait for bootstrap before joining\nif (storageService.isBootstrapMode()) {\n    // poll nodetool netstats / bootstrap_complete before joinRing()\n}","typeGuard":null,"tryCatchPattern":"try { storageService.joinRing(); }\ncatch (IllegalStateException e) { log.warn(\"bootstrap still in progress; retry later\", e); }","preventionTips":["Automate joinRing only after netstats shows no streaming and node is UP/NORMAL.","Monitor bootstrap progress with 'nodetool netstats' and logs.","Investigate stalled streaming promptly instead of forcing the join."],"tags":["cassandra","bootstrap","streaming","illegal-state"],"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-14T16:17:12.679Z"}