grpc/grpc-java · error · IllegalArgumentException

Invalid host or port:

Error message

Invalid host or port: 

What it means

Grpc.authorityFromHostAndPort() builds a URI authority from a host and port using java.net.URI. If the host/port combination is not a valid URI component (e.g. host contains illegal characters, spaces, or an empty host with a port), URISyntaxException is caught and rethrown as IllegalArgumentException beginning with "Invalid host or port: ".

Source

Thrown at api/src/main/java/io/grpc/Grpc.java:162

  /**
   * Creates a channel builder from a host, port, and credentials. The host and port are combined to
   * form an authority string and then passed to {@link #newChannelBuilder(String,
   * ChannelCredentials)}. IPv6 addresses are properly surrounded by square brackets ("[]").
   */
  public static ManagedChannelBuilder<?> newChannelBuilderForAddress(
      String host, int port, ChannelCredentials creds) {
    return newChannelBuilder(authorityFromHostAndPort(host, port), creds);
  }

  /**
   * Combine a host and port into an authority string.
   */
  // A copy of GrpcUtil.authorityFromHostAndPort
  private 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);
    }
  }

  /**
   * Static factory for creating a new ServerBuilder.
   *
   * @param port the port to listen on
   * @param creds the server identity
   */
  public static ServerBuilder<?> newServerBuilderForPort(int port, ServerCredentials creds) {
    return ServerRegistry.getDefaultRegistry().newServerBuilderForPort(port, creds);
  }
}

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Inspect the exception message and cause: it prints the offending host and port — remove illegal characters or whitespace from the host string
2. If you have a full authority or target string, use Grpc.newChannelBuilder(target, creds) with the string form instead of splitting it yourself
3. Trim and validate hostnames from config/env before passing them; for IPv6 pass the bracketed form consistently (host inside brackets, e.g. "[::1]")
4. Check for placeholder or templated values ("<host>", "${HOST}") that were never substituted

Example fix

// before
String host = config.get("grpc.host"); // "localhost:50051" or " myhost "
ManagedChannel ch = Grpc.newChannelBuilder(host, 50051, creds).build();
// after
String host = config.get("grpc.host").trim();
if (host.contains(":") && !host.startsWith("[")) { // full authority passed where host expected
  ManagedChannel ch = Grpc.newChannelBuilder(host, creds).build();
} else {
  ManagedChannel ch = Grpc.newChannelBuilder(host, 50051, creds).build();
}

String host = rawHost == null ? null : rawHost.trim();
if (host == null || host.isEmpty())
  throw new IllegalArgumentException("gRPC host must not be empty");
if (host.contains(" ") || host.matches(".*[<>\"{}|\\^`].*"))
  throw new IllegalArgumentException("gRPC host contains illegal characters: " + host);
try {
  new java.net.URI(null, null, host, port, null, null, null);
} catch (java.net.URISyntaxException e) {
  throw new IllegalArgumentException("Invalid gRPC host/port: " + host + ":" + port, e);
}

try {
  ManagedChannel ch = Grpc.newChannelBuilder(host, port, creds).build();
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Invalid host or port:")) {
    log.error("Bad host/port: {} — check config for full authority strings, whitespace, or placeholders", e.getMessage());
  } else throw e;
}

When it happens

Trigger: Calling Grpc.newChannelBuilder(host, port) / forAddress paths (via newChannelBuilderForAddress) with a host string containing invalid URI characters — spaces, "["/"]" misuse, control characters, an empty host, or a target that was never parsed into host/port properly (e.g. passing "host:port" as the host argument).

Common situations: Passing a full authority string ("localhost:50051") where only the host is expected; untrimmed hostnames read from config or environment variables with whitespace; IPv6 literals not properly bracketed or over-bracketed; placeholder values like "<host>" left in config.

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

• At least one credential is required
• At least one credential is required
• Has authority -- Non-empty path must start with '/'
• No authority -- Path cannot start with '//'
• Missing required scheme.

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