apache/cassandra · error · IllegalStateException

Not starting client transports in write_survey mode as it's

Error message

Not starting client transports in write_survey mode as it's bootstrapping or auth is enabled

What it means

CassandraDaemon refuses to start client transports (native transport, etc.) while the node is in write_survey mode but has not finished its bootstrap/repair phase, or while authentication is required but not yet fully initialized. In write_survey mode a node receives writes but does not back-propagate them, so exposing client traffic before the ring join completes (or before auth is ready) would silently lose or fail writes. The check lives in validateTransportsCanStart and throws IllegalStateException.

Source

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

    {
        DatabaseDescriptor.daemonInitialization();
    }

    public void validateTransportsCanStart()
    {
        ClusterMetadata metadata = ClusterMetadata.current();
        MultiStepOperation<?> startupSequence = metadata.inProgressSequences.get(metadata.myNodeId());

        // We only start transports if bootstrap has completed, and we're not in survey mode, OR if we are in
        // survey mode and streaming has completed, but we're not using auth.
        // OR if we have not joined the ring yet.
        if (startupSequence != null)
        {
            if (StorageService.instance.isSurveyMode())
            {
                if (!StorageService.instance.readyToFinishJoiningRing() || DatabaseDescriptor.isAuthenticationRequired())
                {
                    throw new IllegalStateException("Not starting client transports in write_survey mode as it's bootstrapping or " +
                                                    "auth is enabled");
                }
            }
            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;

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Wait until bootstrap/repair (readyToFinishJoiningRing) completes before calling startNativeTransport / letting start() proceed; check with nodetool netstats/repair status.
If auth is the blocker, complete role/auth setup (e.g. create superuser roles) or temporarily start with a allow-all authenticator in survey mode.
If the node was accidentally started in write_survey mode, restart without -Dcassandra.write_survey so the normal startup sequence runs.
Complete the survey-phase join explicitly (resume join) once the survey is done, then start transports.

Example fix

// before: scripts/start.sh
bin/cassandra -Dcassandra.write_survey=true && nodetool startnativetransport
// after
bin/cassandra -Dcassandra.write_survey=true
# wait until readyToFinishJoiningRing (nodetool netstats shows normal), then:
nodetool resume && nodetool startnativetransport

Defensive patterns

Strategy: validation

Validate before calling

if (StorageService.instance.isSurveyMode() && (!StorageService.instance.readyToFinishJoiningRing() || DatabaseDescriptor.isAuthenticationRequired())) {
    throw new IllegalStateException("Defer client transports until survey bootstrap completes");
}

Try / catch

try { daemon.startNativeTransport(); } catch (IllegalStateException e) { logger.warn("Transports deferred: {}", e.getMessage()); /* retry after ring join */ }

Prevention

Check `nodetool netstats`/join status before enabling native transport in survey mode
Automate the survey->resume->start-transport sequence in orchestration scripts
Remember auth-enabled nodes cannot start transports in write_survey; complete role setup first

When it happens

Trigger: Calling start() or startNativeTransport() on a node started with -Dcassandra.write_survey=true while StorageService.readyToFinishJoiningRing() is false, or while DatabaseDescriptor.isAuthenticationRequired() is true (authenticator configured but the node hasn't completed its startup sequence).

Common situations: Operators boot new datacenters in write_survey mode for DC expansion and try to start the node or enable native transport before bootstrap/repair finished; nodes with PasswordAuthenticator enabled started in survey mode before role setup is complete.

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/e8b16644fdfe5d36. Report an issue: GitHub.