{"record":{"id":"afe2646acd5d1157","repo":"quarkusio/quarkus","slug":"cannot-attach-headers-to-a-null-client","errorCode":null,"errorMessage":"Cannot attach headers to a null client","messagePattern":"Cannot attach headers to a null client","errorType":"exception","errorClass":"NullPointerException","httpStatus":null,"severity":"error","filePath":"extensions/grpc/api/src/main/java/io/quarkus/grpc/GrpcClientUtils.java","lineNumber":26,"sourceCode":"/**\n * gRPC client utilities\n */\npublic class GrpcClientUtils {\n\n    /**\n     * Attach headers to a gRPC client.\n     *\n     * To make a call with headers, first invoke this method and then perform the intended call with the <b>returned</b> client\n     *\n     * @param client any kind of gRPC client\n     * @param extraHeaders headers to attach\n     * @param <T> type of the client\n     * @return a client with headers attached\n     */\n    @SuppressWarnings({ \"unchecked\", \"rawtypes\" })\n    public static <T> T attachHeaders(T client, Metadata extraHeaders) {\n        if (client == null) {\n            throw new NullPointerException(\"Cannot attach headers to a null client\");\n        }\n\n        client = getProxiedObject(client);\n\n        if (client instanceof AbstractStub) {\n            return (T) ((AbstractStub) client).withInterceptors(MetadataUtils.newAttachHeadersInterceptor(extraHeaders));\n        } else if (client instanceof MutinyClient) {\n            MutinyClient mutinyClient = (MutinyClient) client;\n            AbstractStub stub = mutinyClient.getStub()\n                    .withInterceptors(MetadataUtils.newAttachHeadersInterceptor(extraHeaders));\n            return (T) ((MutinyClient) client).newInstanceWithStub(stub);\n        } else {\n            throw new IllegalArgumentException(\"Unsupported client type \" + client.getClass());\n        }\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    public static <T> T getProxiedObject(T client) {","sourceCodeStart":8,"sourceCodeEnd":44,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/grpc/api/src/main/java/io/quarkus/grpc/GrpcClientUtils.java#L8-L44","documentation":"GrpcClientUtils.attachHeaders() explicitly throws a NullPointerException when the client argument is null. The utility unwraps gRPC client proxies and attaches a Metadata interceptor, so it requires a real client instance to operate on. This is a fail-fast guard rather than a silent failure deep in proxy handling.","triggerScenarios":"Calling GrpcClientUtils.attachHeaders(null, metadata), typically when the @GrpcClient-injected bean failed to be injected (e.g. wrong service name in @GrpcClient(\"name\") so the injection point is unsatisfied and resolved to null in non-CDI usage) or a factory method returning null was passed in.","commonSituations":"Misconfigured quarkus.grpc.clients.<name> properties so the client bean is not produced; passing a client obtained from a map/cache lookup that missed; calling the utility in unit tests without a running Quarkus context so the injected field is null.","solutions":["Check why the client reference is null before calling attachHeaders — verify the @GrpcClient injection point name matches a configured client","Ensure the Quarkus application/ArC container is started when the utility is invoked (not plain unit tests without quarkus:test)","Guard the call with a null check and fail with a clearer domain-specific message"],"exampleFix":"// before\nMetadata headers = new Metadata();\nMyGrpc client = null;\nMyGrpc withHeaders = GrpcClientUtils.attachHeaders(client, headers); // NPE\n// after\nif (client == null) {\n    throw new IllegalStateException(\"gRPC client not configured; check @GrpcClient name and quarkus.grpc.clients config\");\n}\nMyGrpc withHeaders = GrpcClientUtils.attachHeaders(client, headers);","handlingStrategy":"validation","validationCode":"if (client == null) {\n    throw new IllegalStateException(\"gRPC client is null; check @GrpcClient configuration\");\n}\nMetadata headers = new Metadata();\nheaders.put(Metadata.Key.of(\"x-key\", Metadata.ASCII_STRING_MARSHALLER), \"value\");\nT safe = GrpcClientUtils.attachHeaders(client, headers);","typeGuard":"boolean isUsableClient(Object c) {\n    return c != null\n        && (c instanceof io.grpc.stub.AbstractStub\n            || c instanceof io.quarkus.grpc.runtime.MutinyClient);\n}","tryCatchPattern":"try {\n    T withHeaders = GrpcClientUtils.attachHeaders(client, headers);\n} catch (NullPointerException e) {\n    throw new IllegalStateException(\"Client was null — injection/config problem\", e);\n}","preventionTips":["Always obtain the client via @GrpcClient injection or GrpcClientFactory, never construct it manually","Verify the @GrpcClient(\"name\") matches a quarkus.grpc.clients.<name> config block","Write an ArC/CDI-based test that asserts the injected client is non-null before using utilities"],"tags":["grpc","null-pointer","client-injection"],"backgroundTag":"null-client-reference","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}