{"record":{"id":"848cbfed85000ea2","repo":"quarkusio/quarkus","slug":"unable-to-retrieve-the-grpc-channel-name","errorCode":null,"errorMessage":"Unable to retrieve the gRPC Channel ${name}","messagePattern":"Unable to retrieve the gRPC Channel (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/grpc/runtime/src/main/java/io/quarkus/grpc/runtime/supports/Channels.java","lineNumber":285,"sourceCode":"            } catch (IOException e) {\n                throw new UncheckedIOException(\"Unable to read \" + resourceName + \" from \" + path, e);\n            }\n        }\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    public static Channel retrieveChannel(String name, Set<String> perClientInterceptors) {\n        ClientInterceptorStorage clientInterceptorStorage = Arc.container().instance(ClientInterceptorStorage.class).get();\n        Annotation[] qualifiers = new Annotation[perClientInterceptors.size() + 1];\n        int idx = 0;\n        qualifiers[idx++] = GrpcClient.Literal.of(name);\n        for (String interceptor : perClientInterceptors) {\n            qualifiers[idx++] = RegisterClientInterceptor.Literal\n                    .of((Class<? extends ClientInterceptor>) clientInterceptorStorage.getPerClientInterceptor(interceptor));\n        }\n        InstanceHandle<Channel> instance = Arc.container().instance(Channel.class, qualifiers);\n        if (!instance.isAvailable()) {\n            throw new IllegalStateException(\"Unable to retrieve the gRPC Channel \" + name);\n        }\n        return instance.get();\n    }\n\n    public static class ChannelDestroyer implements BeanDestroyer<Channel> {\n\n        @Override\n        public void destroy(Channel instance, CreationalContext<Channel> creationalContext, Map<String, Object> params) {\n            if (instance instanceof ManagedChannel) {\n                ManagedChannel channel = (ManagedChannel) instance;\n                LOGGER.info(\"Shutting down gRPC channel \" + channel);\n                channel.shutdownNow();\n                try {\n                    channel.awaitTermination(10, TimeUnit.SECONDS);\n                } catch (InterruptedException e) {\n                    LOGGER.info(\"Unable to shutdown channel after 10 seconds\");\n                    Thread.currentThread().interrupt();\n                }","sourceCodeStart":267,"sourceCodeEnd":303,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/grpc/runtime/src/main/java/io/quarkus/grpc/runtime/supports/Channels.java#L267-L303","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add configuration for the named client, e.g. quarkus.grpc.clients.<name>.host and .port in application.properties","Fix the name passed to @GrpcClient(\"<name>\") so it matches a configured client","Ensure the gRPC extension is present and the application was rebuilt so Channel beans are generated","If retrieving programmatically, verify Arc.container().instance(Channel.class, qualifiers).isAvailable() before calling get()"],"exampleFix":"// before\n@GrpcClient(\"greet\")\nGreeterGrpc.GreeterStub stub; // quarkus.grpc.clients.greet.* not configured\n// after\n# application.properties\nquarkus.grpc.clients.greet.host=localhost\nquarkus.grpc.clients.greet.port=9000","handlingStrategy":"validation","validationCode":"var handle = Arc.container().instance(Channel.class, qualifiers);\nif (handle == null || !handle.isAvailable()) {\n    throw new IllegalStateException(\"gRPC Channel '\" + name + \"' is not configured; add quarkus.grpc.clients.\" + name + \".host/port\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    Channel ch = Channels.retrieveChannel(name);\n} catch (IllegalStateException e) {\n    LOG.errorf(\"gRPC channel '%s' missing — check quarkus.grpc.clients.%s config\", name, name);\n}","preventionTips":["Keep client names in @GrpcClient identical to quarkus.grpc.clients.* keys","Always define host/port for every named client","Rebuild after adding new client config so beans are generated"],"tags":["grpc","cdi","configuration","quarkus"],"backgroundTag":"missing-bean-dependency","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}