{"record":{"id":"7217ddc5e0685629","repo":"quarkusio/quarkus","slug":"native-transport-s-was-requested-quarkus-vertx","errorCode":null,"errorMessage":"Native transport '%s' was requested (quarkus.vertx.native-transport-type=%s) but its dependency is not on the classpath. See the Native Transport Reference guide for the required dependency.","messagePattern":"Native transport '(.+?)' was requested \\(quarkus\\.vertx\\.native-transport-type=(.+?)\\) but its dependency is not on the classpath\\. See the Native Transport Reference guide for the required dependency\\.","errorType":"exception","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"extensions/vertx/deployment/src/main/java/io/quarkus/vertx/core/deployment/VertxCoreProcessor.java","lineNumber":220,"sourceCode":"        if (QuarkusClassLoader.isClassPresentAtRuntime(\"io.netty.channel.kqueue.AcceptFilter\")) {\n            detected.add(NativeTransportType.KQUEUE.transportName);\n        }\n        if (QuarkusClassLoader.isClassPresentAtRuntime(\"io.netty.channel.uring.IoUring\")) {\n            detected.add(NativeTransportType.IO_URING.transportName);\n        }\n\n        NativeTransportType requestedType = buildTimeConfig.nativeTransportType();\n        NativeTransportMode mode = buildTimeConfig.nativeTransport();\n        boolean preferNative = mode != NativeTransportMode.DISABLED || requestedType != NativeTransportType.AUTO;\n\n        if (requestedType != NativeTransportType.AUTO && !detected.contains(requestedType.transportName)) {\n            String msg = String.format(\n                    \"Native transport '%s' was requested (quarkus.vertx.native-transport-type=%s) \"\n                            + \"but its dependency is not on the classpath. \"\n                            + \"See the Native Transport Reference guide for the required dependency.\",\n                    requestedType.transportName, requestedType.name().toLowerCase().replace('_', '-'));\n            if (mode == NativeTransportMode.REQUIRED) {\n                throw new ConfigurationException(msg);\n            }\n            log.warn(msg);\n        } else if (preferNative && detected.isEmpty()) {\n            log.warn(\"Native transport was requested but no native transport dependency was found on the classpath. \"\n                    + \"The application will fall back to Java NIO. \"\n                    + \"See the Native Transport Reference guide for dependency information.\");\n        } else if (!detected.isEmpty()) {\n            log.debugf(\"Detected native transport(s) on classpath: %s\", detected);\n        }\n\n        recorder.setDetectedNativeTransports(detected);\n    }\n\n    @BuildStep\n    LogCleanupFilterBuildItem filterNettyHostsFileParsingWarn() {\n        return new LogCleanupFilterBuildItem(\"io.netty.resolver.HostsFileParser\",\n                \"Failed to load and parse hosts file\");\n    }","sourceCodeStart":202,"sourceCodeEnd":238,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/vertx/deployment/src/main/java/io/quarkus/vertx/core/deployment/VertxCoreProcessor.java#L202-L238","documentation":"quarkus.vertx.native-transport-type requests a native transport (epoll/kqueue/io_uring) but the matching Vert.x native-transport dependency is not on the classpath. If the mode is REQUIRED, the build fails with this ConfigurationException; otherwise only a warning is logged and the app falls back to NIO.","triggerScenarios":"Setting quarkus.vertx.prefer-native-transport / native-transport-type=epoll|kqueue|io_uring without adding the corresponding vertx-transport-native-* dependency.","commonSituations":"Enabling native transport on Linux for performance without adding io.vertx:vertx-transport-native-epoll; wrong transport for the platform (kqueue on Linux); missing classifier dependencies (e.g. :linux-x86_64).","solutions":["Add the matching native dependency, e.g. io.vertx:vertx-transport-native-epoll:<vertx-version> with the correct platform classifier","Set quarkus.vertx.native-transport-type to a transport supported by your OS","If native transport is optional, use PREFER mode and accept the NIO fallback","Verify with `quarkus.vertx.native-transport-type=required` locally first to fail fast"],"exampleFix":"// before (pom.xml): only quarkus-vertx, transport set to epoll\n// after\n<dependency>\n  <groupId>io.vertx</groupId>\n  <artifactId>vertx-transport-native-epoll</artifactId>\n  <classifier>linux-x86_64</classifier>\n</dependency>","handlingStrategy":"validation","validationCode":"// fail fast in CI: assert native dependency present when transport configured\nString type = System.getProperty(\"quarkus.vertx.native-transport-type\", \"none\");\nif (!\"none\".equals(type)) {\n    try { Class.forName(\"io.vertx.core.spi.transport.Transport\"); } catch (ClassNotFoundException e) {\n        throw new IllegalStateException(\"Add vertx-transport-native-\" + type + \" dependency\");\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Match the native dependency and classifier to your target OS/arch","Use native-transport-type=required locally to fail fast","Check the Vert.x Native Transport Reference when upgrading Vert.x"],"tags":["quarkus","vertx","native-transport","missing-dependency","config"],"backgroundTag":"missing-dependency","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"}