grpc/grpc-java · error · GrpcServiceParseException

Target URI scheme is not resolvable: " + targetUri

Error message

Target URI scheme is not resolvable: " + targetUri

What it means

Thrown by GrpcServiceConfigParser.parseGoogleGrpcConfig when the GrpcService's target_uri scheme cannot be resolved: the parser could not parse it as a URI or the scheme is not among the supported ones (e.g. not 'dns' or 'xds'). The client cannot construct a channel to the xDS server described by the target URI, so parsing fails.

Source

Thrown at xds/src/main/java/io/grpc/xds/GrpcServiceConfigParser.java:168

        Optional.ofNullable(allowedGrpcServices.services().get(targetUri));

    boolean isTargetUriSchemeSupported = false;
    try {
      URI uri = new URI(targetUri);
      String scheme = uri.getScheme();
      if (scheme == null) {
        scheme = NameResolverRegistry.getDefaultRegistry().getDefaultScheme();
      }
      if (scheme != null) {
        isTargetUriSchemeSupported =
            NameResolverRegistry.getDefaultRegistry().getProviderForScheme(scheme) != null;
      }
    } catch (URISyntaxException e) {
      // Fallback or ignore if not a valid URI
    }

    if (!isTargetUriSchemeSupported) {
      throw new GrpcServiceParseException("Target URI scheme is not resolvable: " + targetUri);
    }

    if (!isTrustedControlPlane) {
      if (!override.isPresent()) {
        throw new GrpcServiceParseException(
            "Untrusted xDS server & URI not found in allowed_grpc_services: " + targetUri);
      }

      GrpcServiceConfig.GoogleGrpcConfig.Builder builder =
          GrpcServiceConfig.GoogleGrpcConfig.builder().target(targetUri)
              .configuredChannelCredentials(override.get().configuredChannelCredentials());
      if (override.get().callCredentials().isPresent()) {
        builder.callCredentials(override.get().callCredentials().get());
      }
      return builder.build();
    }

    ConfiguredChannelCredentials channelCreds =

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Set target_uri to a supported form, e.g. 'dns:///xds.example.com:443' or an xds-scheme URI matching your bootstrap servers.
2. Verify the target_uri scheme matches what grpc-java supports in your version (dns/xds).
3. Fix characters that break URI parsing (spaces, unencoded non-ASCII) in target_uri.

Example fix

// before
 target_uri: "unix:/var/run/xds.sock"
// after
 target_uri: "dns:///xds.example.com:443"

// Pre-check that target_uri parses and has a supported scheme
URI uri;
try { uri = new URI(targetUri); } catch (URISyntaxException e) {
  throw new IllegalArgumentException("target_uri not a valid URI: " + targetUri); }
String scheme = uri.getScheme();
if (scheme == null || !(scheme.equals("dns") || scheme.equals("xds"))) {
  throw new IllegalArgumentException("unsupported target_uri scheme: " + scheme);
}

try {
  config = GrpcServiceConfigParser.parse(proto, bootstrapInfo, serverInfo);
} catch (GrpcServiceParseException e) {
  if (e.getMessage().startsWith("Target URI scheme")) {
    logger.log(WARNING, "Fix target_uri to dns:///host:port form: " + e.getMessage());
  }
}

When it happens

Trigger: google_grpc.target_uri uses an unsupported or missing scheme (e.g. 'unix:', 'uds://', a bare hostname the parser's URI check rejects, or an empty string), so isTargetUriSchemeSupported stays false after the URI parsing fallback.

Common situations: Control plane configured with unix-socket addresses for the xDS server; target_uri strings like 'xds_cluster' without a scheme; malformed URIs with illegal characters caught by URISyntaxException and then failing the scheme check.

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:
• Has authority -- Non-empty path must start with '/'
• No authority -- Path cannot start with '//'
• Missing required scheme.
• Scheme must start with an alphabetic char

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