What causes "setup() must be called first for CassandraDaemon" in apache/cassandra?

Call cassandraDaemon.setup() (or the full initialize()/start() lifecycle) before invoking startNativeTransport().

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.

Solutions

Call cassandraDaemon.setup() (or the full initialize()/start() lifecycle) before invoking startNativeTransport().
Fix the underlying setup() failure so nativeTransportService is initialized rather than working around the null.
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();

Defensive patterns

Strategy: try-catch

Validate before calling

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

Try / catch

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

Prevention

Always run the full lifecycle setup() -> initialize() -> start() in embedded usage
Never hand-construct CassandraDaemon and call transport methods directly
Check logs for setup() failures — the null service usually means setup aborted early

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

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

Appendix: 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)