quarkusio/quarkus · error · IllegalStateException

Invalid target for the @RegisterInterceptor: ${target}

Error message

Invalid target for the @RegisterInterceptor: ${target}

What it means

@RegisterInterceptor must be placed on a class (the user bean class whose interceptors should apply to generated gRPC beans). If an annotation instance targets anything other than a class, deployment fails.

Source

Thrown at extensions/grpc/deployment/src/main/java/io/quarkus/grpc/deployment/GrpcServerProcessor.java:831

        superfluousInterceptors.remove(RoutingContextGrpcInterceptor.class.getName());

        // Remove the metrics interceptors
        for (String mi : MICROMETER_INTERCEPTORS) {
            superfluousInterceptors.remove(mi);
        }

        List<AnnotationInstance> found = new ArrayList<>(index.getAnnotations(GrpcDotNames.REGISTER_INTERCEPTOR));
        for (AnnotationInstance annotation : index.getAnnotations(GrpcDotNames.REGISTER_INTERCEPTORS)) {
            for (AnnotationInstance nested : annotation.value().asNestedArray()) {
                found.add(AnnotationInstance.create(nested.name(), annotation.target(), nested.values()));
            }
        }

        Map<String, Set<String>> registeredInterceptors = new LinkedHashMap<>();
        for (AnnotationInstance annotation : found) {
            String interceptorClass = annotation.value().asString();
            if (annotation.target().kind() != Kind.CLASS) {
                throw new IllegalStateException("Invalid target for the @RegisterInterceptor: " + annotation.target());
            }
            String targetClass = annotation.target().asClass().name().toString();

            // if the user bean is invoked by a generated bean
            // the interceptors defined on the user bean have to be applied to the generated bean:
            targetClass = delegateMap.getOrDefault(targetClass, targetClass);

            Set<String> registered = registeredInterceptors.computeIfAbsent(targetClass, k -> new LinkedHashSet<>());
            registered.add(interceptorClass);
            superfluousInterceptors.remove(interceptorClass);
        }

        Set<Class<?>> globalInterceptors = new LinkedHashSet<>();
        for (String interceptor : interceptors.globalInterceptors.stream().sorted().toList()) {
            reflectiveClassBuildItemBuildProducer
                    .produce(ReflectiveClassBuildItem.builder(interceptor).constructors(false).build());
            globalInterceptors.add(recorderContext.classProxy(interceptor));
        }

View on GitHub (pinned to e1c734241f)

Solutions

1. Move @RegisterInterceptor to the gRPC service/bean class: @RegisterInterceptor(MyInterceptor.class) on the class
2. Ensure the interceptor class itself is a proper gRPC interceptor
3. Fix any tooling that relocates the annotation

Example fix

// before
class GreeterService {
    @RegisterInterceptor(AuthInterceptor.class)
    public void greet(...) { ... }
}

// after
@RegisterInterceptor(AuthInterceptor.class)
class GreeterService {
    public void greet(...) { ... }
}

// @RegisterInterceptor goes on the class
@RegisterInterceptor(AuthInterceptor.class)
public class GreeterService { ... }

When it happens

Trigger: An @RegisterInterceptor annotation instance found during GrpcServerProcessor.execute whose target().kind() != CLASS — e.g. placed on a method or field instead of the bean class.

Common situations: Misreading the annotation's purpose and attaching it to interceptor methods; code generators misplacing it; copy-paste from @Interceptor conventions.

Related errors

• ${clientAnnotation} may not be declared at ${target}
• Interceptor class ${interceptorClass} is not a CDI bean. Onl
• Unimplemented mode of use of 'io.quarkus.runtime.logging.Log
• Cannot attach headers to a null client
• Unsupported client type " + client.getClass()

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