apache/cassandra · error · IllegalStateException

Node is not yet bootstrapped completely. Use nodetool to che

Error message

Node is not yet bootstrapped completely. Use nodetool to check bootstrap state and resume. For more, see `nodetool help bootstrap`

What it means

Outside a startup sequence, CassandraDaemon.validateTransportsCanStart verifies SystemKeyspace.bootstrapComplete(); if the local node has never recorded bootstrap completion, starting client transports throws this IllegalStateException. It explicitly points operators at nodetool to inspect and resume bootstrap. Nodes started with -Dcassandra.join_ring=false (isStarting) are exempt.

Source

Thrown at src/java/org/apache/cassandra/service/CassandraDaemon.java:932

            else
            {
                throw new IllegalStateException("Node is not yet bootstrapped completely");
            }
        }
        else
        {
            // Bootstrap with same address is an edge-case here, since we rely on HIBERNATE to prevent writes
            // toward the bootstrapping replacement, so there's no startup sequence involved.
            if (StorageService.isReplacingSameAddress() && StorageService.instance.isSurveyMode())
                return;

            // This node has not joined the ring (i.e. it was started with -Dcassandra.join_ring=false)
            if (StorageService.instance.isStarting())
                return;

            if (!SystemKeyspace.bootstrapComplete())
            {
                throw new IllegalStateException("Node is not yet bootstrapped completely. Use nodetool to check bootstrap" +
                                                " state and resume. For more, see `nodetool help bootstrap`");
            }
        }
    }

    public void startNativeTransport()
    {
        validateTransportsCanStart();

        if (nativeTransportService == null)
            throw new IllegalStateException("setup() must be called first for CassandraDaemon");

        // this iterates over a collection of servers and returns true if one of them is started
        boolean alreadyRunning = nativeTransportService.isRunning();

        // this might in practice start all servers which are not started yet
        nativeTransportService.start();

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Run `nodetool bootstrap resume` to continue the interrupted bootstrap, then start transports.
Check bootstrap state and streaming with `nodetool netstats` and `nodetool status`; resolve the underlying failure (disk space, connectivity).
If the node can never join, decommission/wipe the data directories and re-bootstrap from scratch.
If intentionally operating without joining the ring, the node was started with -Dcassandra.join_ring=false — that path is exempt; verify the flag matches intent.

Example fix

// before
cassandra.startNativeTransport();
// after
if (!SystemKeyspace.bootstrapComplete())
    throw new IllegalStateException("Run 'nodetool bootstrap resume' before starting transports");
cassandra.startNativeTransport();

Defensive patterns

Strategy: validation

Validate before calling

if (!SystemKeyspace.bootstrapComplete()) {
    logger.warn("Bootstrap incomplete — run 'nodetool bootstrap resume'");
    return; // don't call startNativeTransport()
}

Try / catch

try { cassandra.startNativeTransport(); } catch (IllegalStateException e) { logger.error("Node not bootstrapped: {} — run nodetool bootstrap resume", e.getMessage()); }

Prevention

Always complete or cleanly abort first bootstrap before restarting nodes
Watch disk space and network during initial streaming (common bootstrap-failure causes)
Check `nodetool netstats` and `nodetool status` in readiness checks
Alert on nodes whose bootstrap never completes within an SLA

When it happens

Trigger: Calling start()/startNativeTransport() on a node whose system.local/system.peers indicate bootstrap never completed — e.g. first start interrupted mid-bootstrap, or a node restarted after a failed initial bootstrap.

Common situations: Disk-full or network failure during initial streaming left bootstrap incomplete; operator restarted the node expecting it to come back up; automation enabled native transport on a freshly provisioned node that never joined the ring.

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

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