quarkusio/quarkus · error · IllegalStateException

Unable to retrieve the gRPC Channel ${name}

Error message

Unable to retrieve the gRPC Channel ${name}

What it means

Quarkus gRPC looks up a named managed gRPC Channel bean in the CDI container (Arc). When no Channel bean is available for the requested name, Channels.retrieveChannel throws this IllegalStateException. It means the gRPC client configuration for that name does not exist or the channel bean was not produced.

Source

Thrown at extensions/grpc/runtime/src/main/java/io/quarkus/grpc/runtime/supports/Channels.java:285

            } catch (IOException e) {
                throw new UncheckedIOException("Unable to read " + resourceName + " from " + path, e);
            }
        }
    }

    @SuppressWarnings("unchecked")
    public static Channel retrieveChannel(String name, Set<String> perClientInterceptors) {
        ClientInterceptorStorage clientInterceptorStorage = Arc.container().instance(ClientInterceptorStorage.class).get();
        Annotation[] qualifiers = new Annotation[perClientInterceptors.size() + 1];
        int idx = 0;
        qualifiers[idx++] = GrpcClient.Literal.of(name);
        for (String interceptor : perClientInterceptors) {
            qualifiers[idx++] = RegisterClientInterceptor.Literal
                    .of((Class<? extends ClientInterceptor>) clientInterceptorStorage.getPerClientInterceptor(interceptor));
        }
        InstanceHandle<Channel> instance = Arc.container().instance(Channel.class, qualifiers);
        if (!instance.isAvailable()) {
            throw new IllegalStateException("Unable to retrieve the gRPC Channel " + name);
        }
        return instance.get();
    }

    public static class ChannelDestroyer implements BeanDestroyer<Channel> {

        @Override
        public void destroy(Channel instance, CreationalContext<Channel> creationalContext, Map<String, Object> params) {
            if (instance instanceof ManagedChannel) {
                ManagedChannel channel = (ManagedChannel) instance;
                LOGGER.info("Shutting down gRPC channel " + channel);
                channel.shutdownNow();
                try {
                    channel.awaitTermination(10, TimeUnit.SECONDS);
                } catch (InterruptedException e) {
                    LOGGER.info("Unable to shutdown channel after 10 seconds");
                    Thread.currentThread().interrupt();
                }

View on GitHub (pinned to e1c734241f)

Solutions

  1. Add configuration for the named client, e.g. quarkus.grpc.clients.<name>.host and .port in application.properties
  2. Fix the name passed to @GrpcClient("<name>") so it matches a configured client
  3. Ensure the gRPC extension is present and the application was rebuilt so Channel beans are generated
  4. If retrieving programmatically, verify Arc.container().instance(Channel.class, qualifiers).isAvailable() before calling get()

Example fix

// before
@GrpcClient("greet")
GreeterGrpc.GreeterStub stub; // quarkus.grpc.clients.greet.* not configured
// after
# application.properties
quarkus.grpc.clients.greet.host=localhost
quarkus.grpc.clients.greet.port=9000
Defensive patterns

Strategy: validation

Validate before calling

var handle = Arc.container().instance(Channel.class, qualifiers);
if (handle == null || !handle.isAvailable()) {
    throw new IllegalStateException("gRPC Channel '" + name + "' is not configured; add quarkus.grpc.clients." + name + ".host/port");
}

Try / catch

try {
    Channel ch = Channels.retrieveChannel(name);
} catch (IllegalStateException e) {
    LOG.errorf("gRPC channel '%s' missing — check quarkus.grpc.clients.%s config", name, name);
}

Prevention

When it happens

Trigger: Calling a generated gRPC client or Channels.retrieveChannel(name) with a service name that has no matching quarkus.grpc.clients.<name> configuration and no registered Channel bean for that name.

Common situations: Typo in the client name in @GrpcClient("...") vs application.properties; missing quarkus.grpc.clients.myclient.host/port config; using a client after the channel bean was destroyed; constructing the client manually instead of via CDI.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/848cbfed85000ea2. Report an issue: GitHub.