quarkusio/quarkus · error · RestClientDefinitionException

Invalid @ClientHeaderParam definition, unable to determine c

Error message

Invalid @ClientHeaderParam definition, unable to determine class %s. Problematic interface: %s

What it means

When @ClientHeaderParam's value is a fully-qualified static method reference (e.g. "com.example.Util#token" or "com.example.Util.token"), the enricher resolves the class portion from the Jandex index. If the class is not in the index, it cannot determine where the method lives and throws at build time.

Source

Thrown at extensions/resteasy-reactive/rest-client/deployment/src/main/java/io/quarkus/rest/client/reactive/deployment/MicroProfileRestClientEnricher.java:852

                                    fillHeader.load(n.getValue()));
                        }
                    });

                } else if (n instanceof RestClientAnnotationExpressionParser.Accessible) {

                    String accessibleName = n.getValue();
                    MethodInfo headerFillingMethod;
                    AccessibleType accessibleType = accessibleName.contains(".") ? AccessibleType.STATIC_METHOD
                            : AccessibleType.INTERFACE_METHOD;
                    if (accessibleType == AccessibleType.STATIC_METHOD) {
                        // calling a static method
                        int endOfClassName = accessibleName.lastIndexOf('.');
                        String className = accessibleName.substring(0, endOfClassName);
                        String staticMethodName = accessibleName.substring(endOfClassName + 1);

                        ClassInfo clazz = index.getClassByName(DotName.createSimple(className));
                        if (clazz == null) {
                            throw new RestClientDefinitionException(String.format(
                                    "Invalid %s definition, unable to determine class %s. Problematic interface: %s",
                                    CLIENT_HEADER_PARAM, className, declaringClass));
                        }
                        headerFillingMethod = findMethod(clazz, declaringClass, staticMethodName,
                                CLIENT_HEADER_PARAM.toString());
                    } else {
                        headerFillingMethod = findMethod(declaringClass, declaringClass, accessibleName,
                                CLIENT_HEADER_PARAM.toString());
                    }

                    Type valueType = null;
                    AtomicInteger parameterPosition = new AtomicInteger(-1);
                    if (headerFillingMethod == null) {
                        for (MethodParameterInfo parameter : declaringMethod.parameters()) {
                            if (!accessibleName.equals(parameter.name())) {
                                continue;
                            }
                            if (!isString(parameter.type())) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Correct the fully-qualified class name in the @ClientHeaderParam value
2. Ensure the class is part of the application (in an indexed module/source)
3. Use a plain method name only if it is a parameter reference (e.g. {param}) instead of a static method

Example fix

// before
@ClientHeaderParam(name = "Token", value = "com.exampel.Utils.token")
// after
@ClientHeaderParam(name = "Token", value = "com.example.Utils.token")

// Ensure the referenced class exists and is loadable before annotating
String ref = "com.example.Utils";
Class.forName(ref); // throws ClassNotFoundException if name is wrong

When it happens

Trigger: value="com.example.Utils.token" where com.example.Utils is not indexed (not in the application archive / missing from Jandex index), or a typo in the package/class name.

Common situations: Referencing a class from an unindexed jar or external module, wrong fully-qualified name after package refactor, or the class lives in a different module not part of the index.

Related errors

• Failed to index: ${className}, class not present in class lo
• Failed to index: ${name}
• Injected class not found in index:
• Unable to properly register the hierarchy of the following J
• Multiple RestClientBuilderFactory implementations found: ${s

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