apache/cassandra · error · IllegalStateException

setup() must be called first for CassandraDaemon

Error message

setup() must be called first for CassandraDaemon

What it means

startNativeTransport requires that CassandraDaemon.setup() has already run and initialized nativeTransportService; if setup() was skipped or failed before the transport service was created, calling startNativeTransport throws this IllegalStateException. The field is null because the native transport service is only constructed during setup.

Source

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

            // 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();

        // interact with gossip only in case if no server was started before to signal they are started now
        if (!alreadyRunning)
            StorageService.instance.setRpcReady(true);
    }

    @Deprecated(since = "5.0.0")
    public void stopNativeTransport()
    {
        stopNativeTransport(false);
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Call cassandraDaemon.setup() (or the full initialize()/start() lifecycle) before invoking startNativeTransport().
2. Fix the underlying setup() failure so nativeTransportService is initialized rather than working around the null.
3. If only transports should be (re)started, call start() which internally validates and starts the initialized services.

Example fix

// before
CassandraDaemon daemon = new CassandraDaemon();
daemon.startNativeTransport();
// after
CassandraDaemon daemon = new CassandraDaemon();
daemon.setup();
daemon.startNativeTransport();

if (daemon instanceof CassandraDaemon && !isSetupComplete(daemon))
    daemon.setup();

try { daemon.startNativeTransport(); } catch (IllegalStateException e) {
    if (e.getMessage().contains("setup() must be called first")) { daemon.setup(); daemon.startNativeTransport(); }
}

When it happens

Trigger: Invoking CassandraDaemon.startNativeTransport() (directly or via startClientTransports) on a CassandraDaemon instance where setup() was never called, or where setup failed before initializing the native transport service.

Common situations: Embedded/testing harnesses that construct CassandraDaemon manually and call startNativeTransport before completing the daemon lifecycle; setup() aborted early due to a config error so nativeTransportService remained null.

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

• No configured daemon
• be positive
• native_transport_min_backoff_on_queue_overload should be str
• Error starting native transport:
• Disabling gossip while native transport is still active is u

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