{"record":{"id":"e216e644fcb85a05","repo":"eclipse-vertx/vert.x","slug":"domain-sockets-require-jdk-16-and-above-or-the-us-e216e6","errorCode":null,"errorMessage":"Domain sockets require JDK 16 and above, or the usage of a native transport","messagePattern":"Domain sockets require JDK 16 and above, or the usage of a native transport","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/spi/transport/Transport.java","lineNumber":63,"sourceCode":"  }\n\n  /**\n   * @return true when the transport is available.\n   */\n  default boolean isAvailable() {\n    return true;\n  }\n\n  /**\n   * @return the error that cause the unavailability when {@link #isAvailable()} returns {@code null}.\n   */\n  default Throwable unavailabilityCause() {\n    return null;\n  }\n\n  default SocketAddress convert(io.vertx.core.net.SocketAddress address) {\n    if (address.isDomainSocket()) {\n      throw new IllegalArgumentException(\"Domain sockets require JDK 16 and above, or the usage of a native transport\");\n    } else {\n      InetAddress ip = ((SocketAddressImpl) address).ipAddress();\n      if (ip != null) {\n        return new InetSocketAddress(ip, address.port());\n      } else {\n        return InetSocketAddress.createUnresolved(address.host(), address.port());\n      }\n    }\n  }\n\n  default io.vertx.core.net.SocketAddress convert(SocketAddress address) {\n    if (address instanceof InetSocketAddress) {\n      return io.vertx.core.net.SocketAddress.inetSocketAddress((InetSocketAddress) address);\n    } else {\n      return null;\n    }\n  }\n","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/spi/transport/Transport.java#L45-L81","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run on JDK 16 or newer, which supports unix domain sockets in the JDK transport.","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).","Use an IP socket (host/port) instead of a domain socket if neither of the above is possible."],"exampleFix":"// before\nVertx vertx = Vertx.builder().build(); // JDK 11, JDK transport\nserver.listen(SocketAddress.domainSocketAddress(\"/tmp/app.sock\"));\n// IllegalArgumentException\n// after\n// Option A: JDK >= 16, or Option B:\nVertx vertx = Vertx.builder()\n  .with(new VertxOptions().setPreferNativeTransport(true))\n  .build(); // with netty-transport-native-epoll/io_uring on classpath\nserver.listen(SocketAddress.domainSocketAddress(\"/tmp/app.sock\"));","handlingStrategy":"validation","validationCode":"if (address.isDomainSocket()) {\n  boolean ok = Runtime.version().feature() >= 16 || vertx.isNativeTransportEnabled();\n  if (!ok) throw new IllegalStateException(\"Domain sockets need JDK 16+ or native transport\");\n}","typeGuard":"boolean canUseDomainSockets(Vertx v) { return Runtime.version().feature() >= 16 || v.isNativeTransportEnabled(); }","tryCatchPattern":"try { return transport.convert(address); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith(\"Domain sockets\")) { /* fall back to TCP socket */ } throw e; }","preventionTips":["Check Runtime.version().feature() >= 16 before configuring unix:/// addresses","Enable native transport (epoll/io_uring) with its Netty dependency when using domain sockets","Use Vertx#isNativeTransportEnabled() to verify at runtime","Provide a TCP fallback host/port config for deployments on older JDKs"],"tags":["domain-sockets","transport","unix-socket","platform"],"backgroundTag":"unsupported-platform","analyzedSha":"fb308bd8c3f12c79f4ae89bef67fadf6c80d036e","analyzedAt":"2026-09-06T11:37:12.241Z","contentChangedAt":"2026-09-06T11:37:12.241Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}