{"record":{"id":"2fdd7d3c1020907e","repo":"apache/cassandra","slug":"epoll-not-available","errorCode":null,"errorMessage":"epoll not available","messagePattern":"epoll not available","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/java/org/apache/cassandra/service/NativeTransportService.java","lineNumber":141,"sourceCode":"        ClientMetrics.instance.release();\n        server = null;\n\n        // shutdown executors used by netty for native transport server\n        if (workerGroup != null)\n            workerGroup.shutdownGracefully(3, 5, TimeUnit.SECONDS).awaitUninterruptibly();\n\n        Dispatcher.shutdown();\n    }\n\n    /**\n     * @return intend to use epoll based event looping\n     */\n    public static boolean useEpoll()\n    {\n        final boolean enableEpoll = NATIVE_EPOLL_ENABLED.getBoolean();\n\n        if (enableEpoll && !Epoll.isAvailable() && NativeLibrary.osType == NativeLibrary.OSType.LINUX)\n            logger.warn(\"epoll not available\", Epoll.unavailabilityCause());\n\n        return enableEpoll && Epoll.isAvailable();\n    }\n\n    /**\n     * @return true in case native transport server is running\n     */\n    public boolean isRunning()\n    {\n        return server != null && server.isRunning();\n    }\n\n    @VisibleForTesting\n    EventLoopGroup getWorkerGroup()\n    {\n        return workerGroup;\n    }\n","sourceCodeStart":123,"sourceCodeEnd":159,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/service/NativeTransportService.java#L123-L159","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the logged Epoll.unavailabilityCause() to identify the underlying load failure","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","If the platform cannot support epoll, explicitly set cassandra.native_epoll_enabled: false to silence the warning and rely on NIO"],"exampleFix":"// before (cassandra.yaml)\nnative_epoll_enabled: true\n\n// after (unsupported container base)\nnative_epoll_enabled: false","handlingStrategy":"fallback","validationCode":"// At startup, detect epoll availability before relying on native transport\nimport io.netty.channel.epoll.Epoll;\nif (Boolean.getBoolean(\"cassandra.native_epoll_enabled\") && !Epoll.isAvailable())\n    System.out.println(\"epoll unavailable: \" + Epoll.unavailabilityCause() + \"; NIO fallback will be used\");","typeGuard":null,"tryCatchPattern":"try {\n    boolean ok = NativeTransportService.useEpoll();\n    System.out.println(\"native transport using \" + (ok ? \"epoll\" : \"nio (fallback)\"));\n} catch (Throwable t) {\n    System.out.println(\"transport init issue: \" + t);\n}","preventionTips":["Use glibc-based container images (not Alpine/musl) for Cassandra","Match the netty-transport-native-epoll classifier to your CPU architecture","Read Epoll.unavailabilityCause() in the warn log at startup; treat it as a deployment checklist item","Explicitly set native_epoll_enabled: false on platforms where epoll natives are unavailable"],"tags":["netty","epoll","native-transport","linux","fallback"],"backgroundTag":"unsupported-platform","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}