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

Capability check in NioTransport.channelFactory: a Unix domain socket channel was requested, but no JDK16+ NioDomainSocketChannel support and no native-transport substitute is available, so the NIO transport cannot create domain-socket channels. The input at fault is the domainSocket=true request in the server/client options.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/impl/transports/NioTransport.java:83

      case IPv4:
        return new NioDatagramChannel(InternetProtocolFamily.IPv4);
      case IPv6:
        return new NioDatagramChannel(InternetProtocolFamily.IPv6);
      default:
        throw new UnsupportedOperationException();
    }
  }

  @Override
  public ChannelFactory<? extends DatagramChannel> datagramChannelFactory() {
    return NioDatagramChannel::new;
  }

  @Override
  public ChannelFactory<? extends Channel> channelFactory(boolean domainSocket) {
    if (domainSocket) {
      if (unixDomainSocketNioTransport == null) {
        throw new IllegalArgumentException("Domain sockets require JDK 16 and above, or the usage of a native transport");
      }
      return NioDomainSocketChannel::new;
    } else {
      return NioSocketChannel::new;
    }
  }

  @Override
  public ChannelFactory<? extends ServerChannel> serverChannelFactory(boolean domainSocket) {
    if (domainSocket) {
      if (unixDomainSocketNioTransport == null) {
        throw new IllegalArgumentException("Domain sockets require JDK 16 and above, or the usage of a native transport");
      }
      return NioServerDomainSocketChannel::new;
    }
    return NioServerSocketChannel::new;
  }

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Run on JDK 16+ or add a native transport (netty-transport-native-epoll/kqueue) to the classpath
2. Disable domain sockets and use TCP when neither is available

When it happens

Trigger: Thrown at vertx-core/src/main/java/io/vertx/core/impl/transports/NioTransport.java:83 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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