quarkusio/quarkus · error · ConfigurationException

Native transport '%s' was requested (quarkus.vertx.native-tr

Error message

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.

What it means

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.

Source

Thrown at extensions/vertx/deployment/src/main/java/io/quarkus/vertx/core/deployment/VertxCoreProcessor.java:220

        if (QuarkusClassLoader.isClassPresentAtRuntime("io.netty.channel.kqueue.AcceptFilter")) {
            detected.add(NativeTransportType.KQUEUE.transportName);
        }
        if (QuarkusClassLoader.isClassPresentAtRuntime("io.netty.channel.uring.IoUring")) {
            detected.add(NativeTransportType.IO_URING.transportName);
        }

        NativeTransportType requestedType = buildTimeConfig.nativeTransportType();
        NativeTransportMode mode = buildTimeConfig.nativeTransport();
        boolean preferNative = mode != NativeTransportMode.DISABLED || requestedType != NativeTransportType.AUTO;

        if (requestedType != NativeTransportType.AUTO && !detected.contains(requestedType.transportName)) {
            String msg = String.format(
                    "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.",
                    requestedType.transportName, requestedType.name().toLowerCase().replace('_', '-'));
            if (mode == NativeTransportMode.REQUIRED) {
                throw new ConfigurationException(msg);
            }
            log.warn(msg);
        } else if (preferNative && detected.isEmpty()) {
            log.warn("Native transport was requested but no native transport dependency was found on the classpath. "
                    + "The application will fall back to Java NIO. "
                    + "See the Native Transport Reference guide for dependency information.");
        } else if (!detected.isEmpty()) {
            log.debugf("Detected native transport(s) on classpath: %s", detected);
        }

        recorder.setDetectedNativeTransports(detected);
    }

    @BuildStep
    LogCleanupFilterBuildItem filterNettyHostsFileParsingWarn() {
        return new LogCleanupFilterBuildItem("io.netty.resolver.HostsFileParser",
                "Failed to load and parse hosts file");
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Add the matching native dependency, e.g. io.vertx:vertx-transport-native-epoll:<vertx-version> with the correct platform classifier
2. Set quarkus.vertx.native-transport-type to a transport supported by your OS
3. If native transport is optional, use PREFER mode and accept the NIO fallback
4. Verify with `quarkus.vertx.native-transport-type=required` locally first to fail fast

Example fix

// before (pom.xml): only quarkus-vertx, transport set to epoll
// after
<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-transport-native-epoll</artifactId>
  <classifier>linux-x86_64</classifier>
</dependency>

// fail fast in CI: assert native dependency present when transport configured
String type = System.getProperty("quarkus.vertx.native-transport-type", "none");
if (!"none".equals(type)) {
    try { Class.forName("io.vertx.core.spi.transport.Transport"); } catch (ClassNotFoundException e) {
        throw new IllegalStateException("Add vertx-transport-native-" + type + " dependency");
    }
}

When it happens

Trigger: Setting quarkus.vertx.prefer-native-transport / native-transport-type=epoll|kqueue|io_uring without adding the corresponding vertx-transport-native-* dependency.

Common situations: 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).

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• Failed to find any non-blocking provider for startup actions
• The class (${name}) cannot be created during deployment.
• Can not add converter ${converter.name()} that is not parame
• Converter ${converter.name()} must be parameterized with a s
• The supplied 'main-class' value of '${mainClassName}' does n

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/7217ddc5e0685629. Report an issue: GitHub.