eclipse-vertx/vert.x · error · IllegalArgumentException

Only socket address are currently supported

Error message

Only socket address are currently supported

What it means

HttpClientImpl.connect resolves the target server from the connect options' server address (used for Unix domain sockets / socket-address based routing). Only InetSocketAddress-like SocketAddress (inet) instances are supported; any other SocketAddress kind throws this IllegalArgumentException.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/HttpClientImpl.java:381

        host = defaultHost;
      }
      server = SocketAddress.inetSocketAddress(port, host);
    } else if (addr instanceof SocketAddress) {
      server = (SocketAddress) addr;
      if (port == null) {
        port = connect.getPort();
      }
      if (host == null) {
        host = connect.getHost();
      }
      if (port == null) {
        port = server.port();
      }
      if (host == null) {
        host = server.host();
      }
    } else {
      throw new IllegalArgumentException("Only socket address are currently supported");
    }
    HttpVersion protocol = connect.getProtocolVersion();
    List<HttpVersion> protocols;
    if (protocol == null) {
      protocols = versions;
    } else {
      protocols = List.of(protocol);
    }
    HostAndPort authority = HostAndPort.create(host, port);
    ClientSSLOptions sslOptions = sslOptions(verifyHost, connect, this.sslOptions);
    ProxyOptions proxyOptions = computeProxyOptions(connect.getProxyOptions(), server);
    ClientMetrics clientMetrics = httpMetrics != null ? httpMetrics.createEndpointMetrics(server, 1) : null;
    Boolean ssl = connect.isSsl();
    boolean useSSL = ssl != null ? ssl : defaultSsl;
    checkClosed();
    HttpConnectParams params = new HttpConnectParams(protocols, sslOptions, proxyOptions, useSSL);
    return transport.connect(vertx.getOrCreateContext(), server, authority, params, clientMetrics)
      .map(conn -> new UnpooledHttpClientConnection(conn).init());

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Use an inet SocketAddress (host + port) via SocketAddress.inetSocketAddress(port, host).
2. Remove the serverAddress from connect options if you did not intend address-based routing.
3. If Unix domain sockets are needed, verify the Vert.x version supports that path or upgrade.

Example fix

// before
options.setServer(new DomainSocketAddress("/tmp/app.sock"));
// after
options.setServer(SocketAddress.inetSocketAddress(8080, "localhost"));

SocketAddress server = connectOptions.getServer();
if (server != null && !server.isInetSocket()) {
  throw new IllegalArgumentException("Use an inet SocketAddress for HTTP client connect");
}

When it happens

Trigger: Passing connect options whose server address is a non-inet SocketAddress implementation (e.g. a domain socket address variant not handled by the code path, or a custom SocketAddress) to HttpClientImpl.connect.

Common situations: Configuring Unix domain socket addresses on a client code path that only supports TCP socket addresses; passing a proxy or routing address of the wrong type; mixing domain-socket examples written for servers into client connect options.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Change group of file not supported
• Invalid url:
• Client is closed
• HTTP client must be configured for at least one HTTP version
• no null chunk accepted

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