eclipse-vertx/vert.x · error · IllegalArgumentException

Invalid authority host portion:

Error message

Invalid authority host portion: 

What it means

HostAndPort.authority(String host, int port) validates the host portion with HttpUtils.isValidHostAuthority and throws IllegalArgumentException if it is not a valid authority (host) form per HTTP semantics. The authority component must not contain characters like '/', '?', '#', '@' or whitespace.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/net/HostAndPort.java:56

   * @param string the string to parse
   * @param schemePort the scheme port used when the optional port is not specified
   * @return the parsed authority or {@code null} when the {@code string} does not represent a valid authority.
   */
  static HostAndPort parseAuthority(String string, int schemePort) {
    return HostAndPortImpl.parseAuthority(string, schemePort);
  }

  /**
   * Create an instance with a valid {@code host} for a valid authority: the {@code host} must
   * match the <i>host</i> rule of <a href="https://datatracker.ietf.org/doc/html/rfc3986#appendix-A">rfc3986</a>.
   *
   * @param host the host portion
   * @param port the port
   * @return the instance
   */
  static HostAndPort authority(String host, int port) {
    if (!HttpUtils.isValidHostAuthority(host)) {
      throw new IllegalArgumentException("Invalid authority host portion: " + host);
    }
    return new HostAndPortImpl(host, port);
  }

  /**
   * Like {@link #authority(String, int)} without a port, {@code -1} is used instead.
   */
  static HostAndPort authority(String host) {
    return authority(host, -1);
  }

  /**
   * @return the host value
   */
  String host();

  /**
   * @return the port value or {@code -1} when not specified

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Strip scheme, userinfo, path and port from the URL/Host header before calling authority()
2. Use java.net.URI parsing (new URI(str)).getHost() to extract the host portion
3. Validate the host with HttpUtils.isValidHostAuthority before calling

Example fix

// before
HostAndPort.authority(request.getHeader("Host"), -1); // may include ':port'
// after
String host = new URI("http://" + request.getHeader("Host")).getHost();
HostAndPort.authority(host, -1);

URI uri = new URI(raw);
String host = uri.getHost();
if (host == null || !io.vertx.core.http.HttpUtils.isValidHostAuthority(host)) {
  throw new IllegalArgumentException("not a valid authority host: " + raw);
}
HostAndPort.authority(host, uri.getPort());

boolean isValidAuthorityHost(String h) { return h != null && !h.isEmpty() && io.vertx.core.http.HttpUtils.isValidHostAuthority(h); }

try {
  HostAndPort hp = HostAndPort.authority(host, port);
} catch (IllegalArgumentException e) {
  log.error("Bad host '{}' - strip scheme/path/userinfo/port first", host, e);
}

When it happens

Trigger: Calling HostAndPort.authority(host, port) with a host string that still contains a scheme, path, userinfo or port, e.g. authority("https://example.com/path", 443), authority("user@example.com", 8080), or an empty/null-ish host string.

Common situations: Parsing a full URL or authority string (like an HTTP Host header) and passing the entire value as the host instead of extracting just the host part; user-supplied hostnames with embedded invalid characters.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• code: <statusCode> (expected: 0+)
• ${message}
• Invalid position for escape character: ${start}
• streamIdleTimeout must be >= 0
• streamReadIdleTimeout must be >= 0

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