quarkusio/quarkus · error · IllegalArgumentException

Annotation is not a registered interceptor binding:

Error message

Annotation is not a registered interceptor binding: 

What it means

ArC maintains the set of interceptor binding annotations registered at build time. When a binding is passed to runtime APIs (verify() used by intercept() etc.), each annotation type is checked against that registry; an unregistered annotation produces IllegalArgumentException('Annotation is not a registered interceptor binding: ...'). The annotation simply isn't a CDI interceptor binding known to the container.

Source

Thrown at independent-projects/arc/runtime/src/main/java/io/quarkus/arc/impl/InterceptorBindings.java:58

            checkInterceptorBindingsForDuplicates(timesQualifierWasSeen);
        }
    }

    // in various cases, specification requires to check interceptor bindings for duplicates and throw IAE
    private static void checkInterceptorBindingsForDuplicates(Map<Class<? extends Annotation>, Integer> timesSeen) {
        timesSeen.forEach(InterceptorBindings::checkInterceptorBindingsForDuplicates);
    }

    private static void checkInterceptorBindingsForDuplicates(Class<? extends Annotation> annClass, Integer timesSeen) {
        if (timesSeen > 1 && !annClass.isAnnotationPresent(Repeatable.class)) {
            throw new IllegalArgumentException("Interceptor binding " + annClass
                    + " was used repeatedly but is not @Repeatable");
        }
    }

    private void verifyInterceptorBinding(Class<? extends Annotation> annotationType) {
        if (!allInterceptorBindings.contains(annotationType.getName())) {
            throw new IllegalArgumentException("Annotation is not a registered interceptor binding: " + annotationType);
        }
    }

    private static class TimesSeenBiFunction implements BiFunction<Class<? extends Annotation>, Integer, Integer> {
        private static final TimesSeenBiFunction INSTANCE = new TimesSeenBiFunction();

        @Override
        public Integer apply(Class<? extends Annotation> k, Integer v) {
            return v == null ? 1 : v + 1;
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Ensure the annotation is declared @InterceptorBinding and its interceptor is a registered bean in the app
2. Check the annotation type you pass — use the actual interceptor binding, not a qualifier or other annotation
3. Verify the library defining the binding is on the app classpath and Jandex-indexed (empty beans.xml or QUARKUS index)
4. Remove the annotation from the binding array if it's not meant to bind interceptors

Example fix

// before
intercept(m, new MyQualifier.Literal()); // not an interceptor binding
// after
@InterceptorBinding @Retention(RUNTIME) @interface Audited {}
intercept(m, new Audited.Literal());

static void requireRegisteredBindings(ArcContainer c, Annotation... bindings) {
    for (Annotation b : bindings) {
        if (!b.annotationType().isAnnotationPresent(InterceptorBinding.class)) {
            throw new IllegalArgumentException(b.annotationType() + " is not an @InterceptorBinding");
        }
    }
}

static boolean isInterceptorBinding(Class<? extends Annotation> a) {
    return a.isAnnotationPresent(jakarta.interceptor.InterceptorBinding.class);
}

try {
    intercept(method, binding);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Annotation is not a registered interceptor binding")) {
        throw new IllegalStateException("Pass only registered @InterceptorBinding annotations", e);
    }
    throw e;
}

When it happens

Trigger: Calling intercept()/Arc container binding APIs with an annotation that is not an @InterceptorBinding (e.g. plain @Qualifier, marker annotation, or a binding from an extension that wasn't processed).

Common situations: Passing a @Qualifier instead of an interceptor binding by mistake; the interceptor/binding lives in a library that wasn't indexed; typos or a similarly-named custom annotation; test code constructing bindings for annotations never bound to an interceptor.

Related errors

• Interceptor binding was used repeatedly but is not @Repeata
• Annotation does not have @Retention(RUNTIME):
• Array component kind is
• @BindingsSource may only define a class type, got ${kind}: $
• The @Blocking, @NonBlocking and @RunOnVirtualThread annotati

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