{"record":{"id":"4a52c79754a90feb","repo":"quarkusio/quarkus","slug":"io-uring-is-not-supported-with-netty-4-2","errorCode":null,"errorMessage":"io_uring is not supported with Netty 4.2","messagePattern":"io_uring is not supported with Netty 4\\.2","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"extensions/smallrye-reactive-messaging-pulsar/runtime/src/main/java/io/quarkus/pulsar/runtime/graal/PulsarSubstitutions.java","lineNumber":20,"sourceCode":"\nimport com.oracle.svm.core.annotate.Substitute;\nimport com.oracle.svm.core.annotate.TargetClass;\n\n/**\n * Pulsar 4.2.x depends on netty-incubator-transport-native-io_uring:0.0.26.Final\n * which was compiled against Netty 4.1.x. Netty 4.2 removed\n * {@code PlatformDependent.getIntVolatile(long)} causing native image linking\n * failures. These substitutions replace the methods that reference the missing\n * API so GraalVM can link the io_uring classes. The substituted methods are\n * never called at runtime because io_uring is opt-in\n * ({@code -Dpulsar.enableUring=true}) and Linux-only.\n */\n@TargetClass(className = \"io.netty.incubator.channel.uring.IOUringEventLoop\")\nfinal class Target_IOUringEventLoop {\n\n    @Substitute\n    protected void run() {\n        throw new UnsupportedOperationException(\"io_uring is not supported with Netty 4.2\");\n    }\n\n    @Substitute\n    protected void cleanup() {\n        throw new UnsupportedOperationException(\"io_uring is not supported with Netty 4.2\");\n    }\n}\n\n@TargetClass(className = \"io.netty.incubator.channel.uring.Native\")\nfinal class Target_IOUringNative {\n\n    @Substitute\n    static Target_RingBuffer createRingBuffer(int ringSize) {\n        throw new UnsupportedOperationException(\"io_uring is not supported with Netty 4.2\");\n    }\n\n    @Substitute\n    static Target_RingBuffer createRingBuffer(int ringSize, int flags) {","sourceCodeStart":2,"sourceCodeEnd":38,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/smallrye-reactive-messaging-pulsar/runtime/src/main/java/io/quarkus/pulsar/runtime/graal/PulsarSubstitutions.java#L2-L38","documentation":"Pulsar's native-image substitutions stub out the legacy Netty io_uring incubator classes because they are incompatible with Netty 4.2. At native runtime, if the legacy IOUringEventLoop is somehow instantiated and its run() executes, it throws UnsupportedOperationException instead of doing real io_uring work.","triggerScenarios":"Running a Pulsar-client application as a native image with Netty 4.2 on the classpath while code explicitly selects the io_uring event loop (e.g. -Dio.netty.transport.preferNative=true or explicit IOUringEventLoopGroup usage).","commonSituations":"Migrating Pulsar apps to Netty 4.2 where the old io_uring incubator dependency is still present and still referenced by transport configuration.","solutions":["Remove the netty-transport-native-epoll/io_uring-incubator legacy wiring and let Netty 4.2's built-in io_uring (io.netty.transport.io_uring) be used","Drop explicit IOUringEventLoopGroup / preferNative selection from client config","Pin Netty to 4.1.x if the incubator io_uring transport is strictly required"],"exampleFix":"// before\nEventLoopGroup group = new IOUringEventLoopGroup();\n// after\nEventLoopGroup group = new NioEventLoopGroup(); // or Netty 4.2 io_uring transport","handlingStrategy":"fallback","validationCode":"// Detect legacy io_uring incubator usage at startup\nClass.forName(\"io.netty.incubator.channel.uring.IOUringEventLoop\");\nif (isNativeImage() && nettyVersion() != null && nettyVersion().startsWith(\"4.2\")) {\n    log.warn(\"Legacy io_uring incubator detected with Netty 4.2 in native mode; falling back to NIO\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    eventLoopGroup = new IOUringEventLoopGroup();\n} catch (Throwable t) {\n    if (t instanceof UnsupportedOperationException) {\n        eventLoopGroup = new NioEventLoopGroup();\n    } else {\n        throw t;\n    }\n}","preventionTips":["Do not add the netty io_uring incubator dependency when building with Netty 4.2","Avoid -Dio.netty.transport.preferNative=true unless the supported 4.2 io_uring transport is used","Test native builds after any Netty version upgrade"],"tags":["native-image","netty","io-uring","pulsar","graal"],"backgroundTag":"io-uring-unsupported","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}