eclipse-vertx/vert.x · error · IllegalArgumentException

Domain sockets require JDK 16 and above, or the usage of a n

Error message

Domain sockets require JDK 16 and above, or the usage of a native transport

What it means

Transport.convert(io.vertx.core.net.SocketAddress) throws IllegalArgumentException when the address is a Unix domain socket but the transport cannot handle it. Domain sockets require either JDK 16+ (where java.net.UnixDomainSocketAddress exists) or a native transport (e.g. io_uring/epoll with the native transport artifact enabled); on unsupported JDKs without native transport, conversion is impossible and the error is thrown.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/spi/transport/Transport.java:63

  }

  /**
   * @return true when the transport is available.
   */
  default boolean isAvailable() {
    return true;
  }

  /**
   * @return the error that cause the unavailability when {@link #isAvailable()} returns {@code null}.
   */
  default Throwable unavailabilityCause() {
    return null;
  }

  default SocketAddress convert(io.vertx.core.net.SocketAddress address) {
    if (address.isDomainSocket()) {
      throw new IllegalArgumentException("Domain sockets require JDK 16 and above, or the usage of a native transport");
    } else {
      InetAddress ip = ((SocketAddressImpl) address).ipAddress();
      if (ip != null) {
        return new InetSocketAddress(ip, address.port());
      } else {
        return InetSocketAddress.createUnresolved(address.host(), address.port());
      }
    }
  }

  default io.vertx.core.net.SocketAddress convert(SocketAddress address) {
    if (address instanceof InetSocketAddress) {
      return io.vertx.core.net.SocketAddress.inetSocketAddress((InetSocketAddress) address);
    } else {
      return null;
    }
  }

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Run on JDK 16 or newer, which supports unix domain sockets in the JDK transport.
2. Add the native transport dependency (e.g. io.netty:netty-transport-native-epoll or -native-io-uring classifier for your platform) and configure Vert.x to use it (VertxOptions/VertxBuilder with the native transport).
3. Use an IP socket (host/port) instead of a domain socket if neither of the above is possible.

Example fix

// before
Vertx vertx = Vertx.builder().build(); // JDK 11, JDK transport
server.listen(SocketAddress.domainSocketAddress("/tmp/app.sock"));
// IllegalArgumentException
// after
// Option A: JDK >= 16, or Option B:
Vertx vertx = Vertx.builder()
  .with(new VertxOptions().setPreferNativeTransport(true))
  .build(); // with netty-transport-native-epoll/io_uring on classpath
server.listen(SocketAddress.domainSocketAddress("/tmp/app.sock"));

if (address.isDomainSocket()) {
  boolean ok = Runtime.version().feature() >= 16 || vertx.isNativeTransportEnabled();
  if (!ok) throw new IllegalStateException("Domain sockets need JDK 16+ or native transport");
}

boolean canUseDomainSockets(Vertx v) { return Runtime.version().feature() >= 16 || v.isNativeTransportEnabled(); }

try { return transport.convert(address); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Domain sockets")) { /* fall back to TCP socket */ } throw e; }

When it happens

Trigger: Binding or connecting to a unix:///domain socket address (SocketAddress.domainSocketAddress(...)) while running on JDK < 16 with the JDK (NIO) transport and no native transport on the classpath/enabled.

Common situations: Unix domain socket server/client config on older JDKs (8/11); Docker containers running an older JDK; forgetting to add the netty-transport-native-epoll/io_uring dependency or not enabling the native transport in Vert.xOptions; defaulting to a domain socket path that only works in some deployments.

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.

AI-assisted analysis of eclipse-vertx/vert.x@fb308bd8c3 (2026-09-06). Data as JSON: /api/errors/e216e644fcb85a05. Report an issue: GitHub.