What causes "must provide eventLoop" in apache/cassandra?

Pass the EventLoop obtained from the SocketFactory's outbound group (e.g. group.next()) to newClientBootstrap

apache/cassandra · error · IllegalArgumentException

must provide eventLoop

Error message

must provide eventLoop

What it means

Fired in SocketFactory.newClientBootstrap as a guard: a null eventLoopGroup is passed where a Netty event loop group is mandatory for building the outbound messaging client bootstrap. It is an internal precondition violation (IllegalStateException/IllegalArgumentException 'must provide eventLoop'), not a user-facing config error.

Source

Thrown at src/java/org/apache/cassandra/net/SocketFactory.java:203

    final ExecutorService synchronousWorkExecutor = executorFactory().pooled("Messaging-SynchronousWork", Integer.MAX_VALUE);

    SocketFactory()
    {
        this(Provider.optimalProvider());
    }

    SocketFactory(Provider provider)
    {
        this.provider = provider;
        this.acceptGroup = provider.makeEventLoopGroup(1, "Messaging-AcceptLoop");
        this.defaultGroup = provider.makeEventLoopGroup(EVENT_THREADS, NamedThreadFactory.globalPrefix() + "Messaging-EventLoop");
        this.outboundStreamingGroup = provider.makeEventLoopGroup(EVENT_THREADS, "Streaming-EventLoop");
    }

    Bootstrap newClientBootstrap(EventLoop eventLoop, int tcpUserTimeoutInMS)
    {
        if (eventLoop == null)
            throw new IllegalArgumentException("must provide eventLoop");

        Bootstrap bootstrap = new Bootstrap().group(eventLoop).channelFactory(provider.clientChannelFactory());

        if (provider == Provider.EPOLL)
            bootstrap.option(EpollChannelOption.TCP_USER_TIMEOUT, tcpUserTimeoutInMS);

        return bootstrap;
    }

    ServerBootstrap newServerBootstrap()
    {
        return new ServerBootstrap().group(acceptGroup, defaultGroup).channelFactory(provider.serverChannelFactory());
    }

    /**
     * Creates a new {@link SslHandler} from provided SslContext.
     * @param peer enables endpoint verification for remote address when not null
     */

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Pass the EventLoop obtained from the SocketFactory's outbound group (e.g. group.next()) to newClientBootstrap
Ensure connection setup only runs after event loop group initialization completes
In tests, provide a real event loop rather than null

Example fix

// before
Bootstrap b = factory.newClientBootstrap(null, tcpUserTimeout);
// after
EventLoop loop = factory.outboundEventLoopGroup().next();
Bootstrap b = factory.newClientBootstrap(loop, tcpUserTimeout);

Defensive patterns

Strategy: validation

Validate before calling

if (eventLoop == null || eventLoop.isShutdown()) throw new IllegalStateException("event loop not ready");

Prevention

Always source the EventLoop from the factory's outbound event loop group
Initialize the event loop group before any connection setup
In tests, inject a real event loop, not null

When it happens

Trigger: Calling newClientBootstrap(null, timeout), typically because an outbound connection/channel factory was constructed without first obtaining an event loop from the provider's event loop group.

Common situations: Custom/patched transport wiring, test code building a bootstrap manually, or initialization ordering bugs where connection setup runs before the messaging event loop group is created.

Related errors

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