apache/cassandra · warning

epoll not available

Error message

epoll not available

What it means

A WARN log (not an exception) from NativeTransportService.useEpoll. When the epoll native transport is enabled via cassandra.native_epoll_enabled and the process runs on Linux, but Netty's Epoll native library is unavailable, Cassandra logs 'epoll not available' with the unavailability cause, then falls back to NIO by returning false. The CQL native transport still works; only the transport implementation differs.

Solutions

1. Read the logged Epoll.unavailabilityCause() to identify the underlying load failure
2. Install the matching native library / use a glibc-based image (or the netty-transport-native-epoll classifier matching your arch), or use the official cassandra image
3. If the platform cannot support epoll, explicitly set cassandra.native_epoll_enabled: false to silence the warning and rely on NIO

Example fix

// before (cassandra.yaml)
native_epoll_enabled: true

// after (unsupported container base)
native_epoll_enabled: false

// At startup, detect epoll availability before relying on native transport
import io.netty.channel.epoll.Epoll;
if (Boolean.getBoolean("cassandra.native_epoll_enabled") && !Epoll.isAvailable())
    System.out.println("epoll unavailable: " + Epoll.unavailabilityCause() + "; NIO fallback will be used");

try {
    boolean ok = NativeTransportService.useEpoll();
    System.out.println("native transport using " + (ok ? "epoll" : "nio (fallback)"));
} catch (Throwable t) {
    System.out.println("transport init issue: " + t);
}

When it happens

Trigger: useEpoll() is called during initialize() of the native transport server while NATIVE_EPOLL_ENABLED is true, Epoll.isAvailable() is false (native lib failed to load), and NativeLibrary.osType is LINUX.

Common situations: Running Cassandra inside containers/musl-based images (Alpine) lacking the glibc epoll netty native; unsupported architectures (ARM with mismatched netty-transport-native-epoll artifact); stripped-down JRE images without the netty native jar; running on Linux distros where the native .so cannot be extracted.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

• be positive
• channel's transferring state is currently set to true…
• Compression provider
• Connection Error
• Disabling gossip while native transport is still active is…

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

Appendix: source

Thrown at src/java/org/apache/cassandra/service/NativeTransportService.java:141

        ClientMetrics.instance.release();
        server = null;

        // shutdown executors used by netty for native transport server
        if (workerGroup != null)
            workerGroup.shutdownGracefully(3, 5, TimeUnit.SECONDS).awaitUninterruptibly();

        Dispatcher.shutdown();
    }

    /**
     * @return intend to use epoll based event looping
     */
    public static boolean useEpoll()
    {
        final boolean enableEpoll = NATIVE_EPOLL_ENABLED.getBoolean();

        if (enableEpoll && !Epoll.isAvailable() && NativeLibrary.osType == NativeLibrary.OSType.LINUX)
            logger.warn("epoll not available", Epoll.unavailabilityCause());

        return enableEpoll && Epoll.isAvailable();
    }

    /**
     * @return true in case native transport server is running
     */
    public boolean isRunning()
    {
        return server != null && server.isRunning();
    }

    @VisibleForTesting
    EventLoopGroup getWorkerGroup()
    {
        return workerGroup;
    }

View on GitHub (pinned to 88fd0f6a0e)