grpc/grpc-java · error · IllegalArgumentException

Invalid authority:

Error message

Invalid authority: 

What it means

GrpcUtil.authorityToUri converts a channel authority string into a URI with only a scheme-less authority component. URIs built from an authority are strict; if the authority is null-checked OK but syntactically invalid (illegal characters, bad IPv6 literal, etc.), the URISyntaxException is rethrown as IllegalArgumentException("Invalid authority: ...").

Source

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

  }

  /**
   * Returns the build version of gRPC.
   */
  public static GrpcBuildVersion getGrpcBuildVersion() {
    return new GrpcBuildVersion("gRPC Java", IMPLEMENTATION_VERSION);
  }

  /**
   * Parse an authority into a URI for retrieving the host and port.
   */
  public static URI authorityToUri(String authority) {
    Preconditions.checkNotNull(authority, "authority");
    URI uri;
    try {
      uri = new URI(null, authority, null, null, null);
    } catch (URISyntaxException ex) {
      throw new IllegalArgumentException("Invalid authority: " + authority, ex);
    }
    return uri;
  }

  /**
   * Verify {@code authority} is valid for use with gRPC. The syntax must be valid and it must not
   * include userinfo.
   *
   * @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;
  }

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Fix the authority string: URL-escape or remove illegal characters, and bracket IPv6 literals like [::1]:50051.
2. Build the authority with GrpcUtil.authorityFromHostAndPort(host, port) instead of manual string concatenation.
3. Validate the authority with `new URI(null, authority, null, null, null)` in a try/catch before passing it to the channel builder.

Example fix

// before
String authority = "my_host_underscore:50051"; // rejected by URI
// after
String authority = GrpcUtil.authorityFromHostAndPort("myhost", 50051);

try {
  new URI(null, authority, null, null, null);
} catch (URISyntaxException e) {
  throw new IllegalArgumentException("Illegal authority: " + authority, e);
}

try {
  uri = GrpcUtil.authorityToUri(authority);
} catch (IllegalArgumentException e) {
  // sanitize/rebuild the authority
}

When it happens

Trigger: Calling withTargetAuthority / building a channel with an authority string that java.net.URI rejects, e.g. containing spaces, underscores, an unbracketed IPv6 address, or other illegal characters.

Common situations: Passing raw host:port with special characters as the authority; constructing authority from user input without validation; IPv6 targets written without [ ] brackets.

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

• Refresh interval must be greater than 0
• Invalid host or port:
• cannot create a NameResolver for ${targetUri}
• Could not find a NameResolverProvider for %s%s
• Cronet does not support overriding authority

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