grpc/grpc-java · error · IllegalArgumentException

Invalid host or port:

Error message

Invalid host or port: 

What it means

GrpcUtil.authorityFromHostAndPort formats a host and port into a valid authority via java.net.URI. If either the host (e.g. empty, illegal characters, unbracketed IPv6) or port (e.g. negative or > 65535) makes URI construction fail, the URISyntaxException is wrapped and rethrown as IllegalArgumentException("Invalid host or port: ...").

Source

Thrown at core/src/main/java/io/grpc/internal/GrpcUtil.java:550

   * @return the {@code authority} provided
   */
  public static String checkAuthority(String authority) {
    URI uri = authorityToUri(authority);
    // Verify that the user Info is not provided.
    checkArgument(uri.getAuthority().indexOf('@') == -1,
        "Userinfo must not be present on authority: '%s'", authority);
    return authority;
  }

  /**
   * Combine a host and port into an authority string.
   */
  // There is a copy of this method in io.grpc.Grpc
  public static String authorityFromHostAndPort(String host, int port) {
    try {
      return new URI(null, null, host, port, null, null, null).getAuthority();
    } catch (URISyntaxException ex) {
      throw new IllegalArgumentException("Invalid host or port: " + host + " " + port, ex);
    }
  }

  /**
   * Shared executor for channels.
   */
  public static final Resource<Executor> SHARED_CHANNEL_EXECUTOR =
      new Resource<Executor>() {
        private static final String NAME = "grpc-default-executor";
        @Override
        public Executor create() {
          return Executors.newCachedThreadPool(getThreadFactory(NAME + "-%d", true));
        }

        @Override
        public void close(Executor instance) {
          ((ExecutorService) instance).shutdown();
        }

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Correct the host and port values: validate the port is 0-65535 and format IPv6 hosts with brackets before calling.
2. Parse endpoints with existing helpers (e.g. InetSocketAddress / GrpcUtil authorities) rather than splitting strings manually.
3. Pre-validate inputs: `if (port < 0 || port > 65535) throw ...` and check host legality with new URI(null, null, host, port, ...) in a guard.

Example fix

// before
String authority = GrpcUtil.authorityFromHostAndPort("::1", 50051); // URI fails
// after
String authority = GrpcUtil.authorityFromHostAndPort("[::1]", 50051);

if (port < 0 || port > 65535) throw new IllegalArgumentException("port out of range: " + port);
if (host.contains(":") && !host.startsWith("[")) host = "[" + host + "]";

try {
  authority = GrpcUtil.authorityFromHostAndPort(host, port);
} catch (IllegalArgumentException e) {
  // report invalid endpoint to caller
}

When it happens

Trigger: Calling authorityFromHostAndPort with an invalid host string (spaces, bad IPv6 without brackets) or an out-of-range port (< 0 or > 65535), typically from a target string parsed into host/port for a channel builder.

Common situations: Parsing target strings like "host:99999" or "[::1]:50051" manually and losing the brackets; user-supplied endpoints; ports read from config as arbitrary integers.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• Invalid host or port:
• Invalid port
• Invalid authority:
• cannot create a NameResolver for ${targetUri}
• Could not find a NameResolverProvider for %s%s

AI-assisted analysis of grpc/grpc-java@64daddc1f3 (2026-09-08). Data as JSON: /api/errors/b316bbfe5f645765. Report an issue: GitHub.