{"record":{"id":"45c4babf9be598b8","repo":"grpc/grpc-java","slug":"invalid-host-or-port","errorCode":null,"errorMessage":"Invalid host or port: ","messagePattern":"Invalid host or port: ","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/io/grpc/Grpc.java","lineNumber":162,"sourceCode":"  /**\n   * Creates a channel builder from a host, port, and credentials. The host and port are combined to\n   * form an authority string and then passed to {@link #newChannelBuilder(String,\n   * ChannelCredentials)}. IPv6 addresses are properly surrounded by square brackets (\"[]\").\n   */\n  public static ManagedChannelBuilder<?> newChannelBuilderForAddress(\n      String host, int port, ChannelCredentials creds) {\n    return newChannelBuilder(authorityFromHostAndPort(host, port), creds);\n  }\n\n  /**\n   * Combine a host and port into an authority string.\n   */\n  // A copy of GrpcUtil.authorityFromHostAndPort\n  private static String authorityFromHostAndPort(String host, int port) {\n    try {\n      return new URI(null, null, host, port, null, null, null).getAuthority();\n    } catch (URISyntaxException ex) {\n      throw new IllegalArgumentException(\"Invalid host or port: \" + host + \" \" + port, ex);\n    }\n  }\n\n  /**\n   * Static factory for creating a new ServerBuilder.\n   *\n   * @param port the port to listen on\n   * @param creds the server identity\n   */\n  public static ServerBuilder<?> newServerBuilderForPort(int port, ServerCredentials creds) {\n    return ServerRegistry.getDefaultRegistry().newServerBuilderForPort(port, creds);\n  }\n}\n","sourceCodeStart":144,"sourceCodeEnd":176,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/api/src/main/java/io/grpc/Grpc.java#L144-L176","documentation":"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: \".","triggerScenarios":"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).","commonSituations":"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.","solutions":["Inspect the exception message and cause: it prints the offending host and port — remove illegal characters or whitespace from the host string","If you have a full authority or target string, use Grpc.newChannelBuilder(target, creds) with the string form instead of splitting it yourself","Trim and validate hostnames from config/env before passing them; for IPv6 pass the bracketed form consistently (host inside brackets, e.g. \"[::1]\")","Check for placeholder or templated values (\"<host>\", \"${HOST}\") that were never substituted"],"exampleFix":"// before\nString host = config.get(\"grpc.host\"); // \"localhost:50051\" or \" myhost \"\nManagedChannel ch = Grpc.newChannelBuilder(host, 50051, creds).build();\n// after\nString host = config.get(\"grpc.host\").trim();\nif (host.contains(\":\") && !host.startsWith(\"[\")) { // full authority passed where host expected\n  ManagedChannel ch = Grpc.newChannelBuilder(host, creds).build();\n} else {\n  ManagedChannel ch = Grpc.newChannelBuilder(host, 50051, creds).build();\n}","handlingStrategy":"validation","validationCode":"String host = rawHost == null ? null : rawHost.trim();\nif (host == null || host.isEmpty())\n  throw new IllegalArgumentException(\"gRPC host must not be empty\");\nif (host.contains(\" \") || host.matches(\".*[<>\\\"{}|\\\\^`].*\"))\n  throw new IllegalArgumentException(\"gRPC host contains illegal characters: \" + host);\ntry {\n  new java.net.URI(null, null, host, port, null, null, null);\n} catch (java.net.URISyntaxException e) {\n  throw new IllegalArgumentException(\"Invalid gRPC host/port: \" + host + \":\" + port, e);\n}","typeGuard":null,"tryCatchPattern":"try {\n  ManagedChannel ch = Grpc.newChannelBuilder(host, port, creds).build();\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().startsWith(\"Invalid host or port:\")) {\n    log.error(\"Bad host/port: {} — check config for full authority strings, whitespace, or placeholders\", e.getMessage());\n  } else throw e;\n}","preventionTips":["Trim hostname strings read from config/env files before use","Never pass a full authority (host:port) or target URI into an API expecting only the host","Validate placeholders and templated values are substituted before building channels","Bracket IPv6 literals consistently ([::1]) and pass them as the host argument"],"tags":["illegal-argument","uri","host","validation"],"backgroundTag":"invalid-url-format","analyzedSha":"64daddc1f3d1975670f769f3e97bde8b2ba32d25","analyzedAt":"2026-09-08T06:14:57.704Z","contentChangedAt":"2026-09-08T06:14:57.704Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}