grpc/grpc-java · error · IllegalArgumentException

cannot create a NameResolver for ${targetUri}

Error message

cannot create a NameResolver for ${targetUri}

What it means

ManagedChannelImpl.getNameResolver asks the NameResolverProvider to create a resolver for the target URI. When the provider returns null — the target URI's scheme is unknown or the URI is malformed for the installed resolvers — the channel constructor fails fast with this IllegalArgumentException, since a channel cannot operate without name resolution.

Source

Thrown at core/src/main/java/io/grpc/internal/ManagedChannelImpl.java:691

    this.channelz = checkNotNull(builder.channelz);
    channelz.addRootChannel(this);

    if (!lookUpServiceConfig) {
      if (defaultServiceConfig != null) {
        channelLogger.log(
            ChannelLogLevel.INFO, "Service config look-up disabled, using default service config");
      }
      serviceConfigUpdated = true;
    }
  }

  @VisibleForTesting
  static NameResolver getNameResolver(
      UriWrapper targetUri, @Nullable final String overrideAuthority,
      NameResolverProvider provider, NameResolver.Args nameResolverArgs) {
    NameResolver resolver = targetUri.newNameResolver(provider, nameResolverArgs);
    if (resolver == null) {
      throw new IllegalArgumentException("cannot create a NameResolver for " + targetUri);
    }

    // We wrap the name resolver in a RetryingNameResolver to give it the ability to retry failures.
    // TODO: After a transition period, all NameResolver implementations that need retry should use
    //       RetryingNameResolver directly and this step can be removed.
    NameResolver usedNameResolver = RetryingNameResolver.wrap(resolver, nameResolverArgs);

    if (overrideAuthority == null) {
      return usedNameResolver;
    }

    return new ForwardingNameResolver(usedNameResolver) {
      @Override
      public String getServiceAuthority() {
        return overrideAuthority;
      }
    };
  }

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Fix the target string to a valid URI, e.g. 'dns:///localhost:50051'.
2. Ensure the NameResolver provider for the scheme is on the classpath (grpc-core's dns resolver is registered via META-INF/services).
3. If using a custom scheme, register its NameResolverProvider with NameResolverRegistry.getDefaultRegistry().
4. Validate the target with target.toString()/URI parsing before building the channel.

Example fix

// before
ManagedChannel ch = ManagedChannelBuilder.forTarget("my-scheme://svc").build();
// after
ManagedChannel ch = ManagedChannelBuilder.forTarget("dns:///svc.example.com:50051").build();

static boolean resolvableTarget(String target) {
  java.net.URI uri = java.net.URI.create(target);
  String scheme = uri.getScheme() == null ? "dns" : uri.getScheme();
  return !io.grpc.NameResolverRegistry.getDefaultRegistry()
      .providers().stream().noneMatch(p -> scheme.equals(p.getDefaultScheme()));
}
// call before forTarget(); also verify URI parses

try {
  return ManagedChannelBuilder.forTarget(target).build();
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("cannot create a NameResolver")) {
    return ManagedChannelBuilder.forTarget("dns:///" + target).build();
  }
  throw e;
}

When it happens

Trigger: ManagedChannelBuilder.forTarget("foo://bar") with an unregistered scheme, a target string like "localhost:port" with no dns resolver available on the classpath, or an invalid authority/syntax the URI wrapper cannot parse.

Common situations: Missing grpc-services/dns resolution dependency in a shaded or minimal deployment; typos in target strings such as 'unix:/path' without the unix transport on the classpath; passing a bare hostname when a scheme is required by custom providers.

Understand the failure class

Background: "Invalid URL" / "URL cannot be empty": fix the malformed or missing URL behind request-construction failures — this error's family across 50 libraries.

Related errors

• Unable to load OkHttpChannelProvider
• OkHttpChannelBuilder not found on the classpath
• No functional channel service provider found. Try adding a d
• No functional channel service provider found. Try adding a d
• ScheduledExecutorService not set in Builder

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