quarkusio/quarkus · error · RestClientDefinitionException

Class ${className} used in ${annotationName} on ${declaringC

Error message

Class ${className} used in ${annotationName} on ${declaringClass} not found

What it means

When a REST client parameter annotation value uses a static-method reference (e.g. @DefaultValue(value = "com.acme.Util#defaultQ")), the enricher resolves the referenced class from the Jandex index. If the class named before the last '.'/'#' in the value is not in the index, the build fails with this RestClientDefinitionException.

Source

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

            TryBlock tryBlock = null;

            if (!required) {
                tryBlock = creator.tryBlock();
                methodCallCreator = tryBlock;
            }
            String methodName = values[0].substring(1, values[0].length() - 1); // strip curly braces

            MethodInfo paramValueMethod;
            ResultHandle paramValue;
            if (methodName.contains(".")) {
                // calling a static method
                int endOfClassName = methodName.lastIndexOf('.');
                String className = methodName.substring(0, endOfClassName);
                String staticMethodName = methodName.substring(endOfClassName + 1);

                ClassInfo clazz = index.getClassByName(DotName.createSimple(className));
                if (clazz == null) {
                    throw new RestClientDefinitionException(
                            "Class " + className + " used in " + annotationName + " on " + declaringClass + " not found");
                }
                paramValueMethod = findMethod(clazz, declaringClass, staticMethodName, clientParamAnnotation.toString());

                if (paramValueMethod.parametersCount() == 0) {
                    paramValue = methodCallCreator.invokeStaticMethod(paramValueMethod);
                } else if (paramValueMethod.parametersCount() == 1 && isString(paramValueMethod.parameterType(0))) {
                    paramValue = methodCallCreator.invokeStaticMethod(paramValueMethod, methodCallCreator.load(paramName));
                } else {
                    throw new RestClientDefinitionException(
                            annotationName + " method " + declaringClass.toString() + "#" + staticMethodName
                                    + " has too many parameters, at most one parameter, param name, expected");
                }
            } else {
                // interface method
                String mockName = mockInterface(declaringClass, generatedClasses, index);
                ResultHandle interfaceMock = methodCallCreator.newInstance(MethodDescriptor.ofConstructor(mockName));

View on GitHub (pinned to e1c734241f)

Solutions

Correct the fully-qualified class name in the annotation value
Ensure the referenced class is in the application (or an indexed dependency), not an unindexed jar
Use the app-model/index-supported location — move the helper class into the application module
Verify the static method exists on the class with the expected signature (next step after this check)

Example fix

// before
@QueryParam("q") @DefaultValue("com.acme.Uttil#defaultQ") String q // typo: Uttil
// after
@QueryParam("q") @DefaultValue("com.acme.Util#defaultQ") String q

Defensive patterns

Strategy: validation

Validate before calling

String methodName = "com.acme.Util#defaultQ"; // from annotation value
String cls = methodName.substring(0, methodName.lastIndexOf('.'));
try {
    Class.forName(cls); // must be loadable & part of the indexed app
} catch (ClassNotFoundException e) {
    throw new IllegalStateException("Class " + cls + " referenced in annotation not found");
}

Try / catch

try {
    enricher.addParam(...);
} catch (RestClientDefinitionException e) {
    if (e.getMessage().contains("not found")) { /* fix class reference */ }
    throw e;
}

Prevention

Use the exact fully-qualified class name in '#'-style annotation values
Keep referenced helper classes in the application module (indexed by Quarkus/Jandex)
Grep for '#'-method references in @DefaultValue/@QueryParam values after package refactors
Verify static method existence and zero-arg signature on the referenced class

When it happens

Trigger: An annotation value references com.acme.Util#someMethod but the class com.acme.Util is not part of the indexed application classes (not on the app classpath / not in the Quarkus index), or the class name string is misspelled.

Common situations: Typos in the fully-qualified class name; class lives in a dependency not indexed by Quarkus; class removed in a refactor while annotation values still reference it; wrong package after a move.

Related errors

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