quarkusio/quarkus · error · IllegalArgumentException

Annotation instance ${annotationInstance} does not match ann

Error message

Annotation instance ${annotationInstance} does not match annotation type ${annotationType.getName()}

What it means

AnnotationProxyProvider.builder() creates runtime annotation literals from Jandex AnnotationInstance data. It validates that the instance's annotation name equals the requested annotation type's binary name; a mismatch means the caller passed an instance of a different annotation than the literal is being built for, which would produce a wrongly-typed proxy.

Source

Thrown at core/deployment/src/main/java/io/quarkus/deployment/recording/AnnotationProxyProvider.java:59

    private final ClassLoader classLoader;
    private final IndexView index;

    AnnotationProxyProvider(IndexView index) {
        this.annotationLiterals = new ConcurrentHashMap<>();
        this.annotationClasses = new ConcurrentHashMap<>();
        this.generatedLiterals = new ConcurrentHashMap<>();
        this.index = index;
        ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
        if (classLoader == null) {
            classLoader = AnnotationProxy.class.getClassLoader();
        }
        this.classLoader = classLoader;
    }

    public <A extends Annotation> AnnotationProxyBuilder<A> builder(AnnotationInstance annotationInstance,
            Class<A> annotationType) {
        if (!annotationInstance.name().toString().equals(annotationType.getName())) {
            throw new IllegalArgumentException("Annotation instance " + annotationInstance + " does not match annotation type "
                    + annotationType.getName());
        }
        ClassInfo annotationClass = annotationClasses.computeIfAbsent(annotationInstance.name(), name -> {
            ClassInfo clazz = index.getClassByName(name);
            if (clazz == null) {
                try (InputStream annotationStream = IoUtil.readClass(classLoader, name.toString())) {
                    clazz = Index.singleClass(annotationStream);
                } catch (Exception e) {
                    throw new IllegalStateException("Failed to index: " + name, e);
                }
            }
            return clazz;
        });
        String annotationLiteral = annotationLiterals.computeIfAbsent(annotationInstance.name(),
                // com.foo.MyAnnotation -> com.foo.MyAnnotation_Proxy_AnnotationLiteral
                name -> name + "_Proxy_AnnotationLiteral");

        return new AnnotationProxyBuilder<>(annotationInstance, annotationType, annotationLiteral, annotationClass);

View on GitHub (pinned to e1c734241f)

Solutions

1. Filter AnnotationInstances by exact name before calling builder(): instance.name().toString().equals(AnnotationType.class.getName())
2. Use index.getAnnotations(DotName.createSimple(AnnotationType.class.getName())) to fetch only matching instances
3. Check for duplicate/wrong imports of the annotation class (same simple name, different package)

Example fix

// before
for (AnnotationInstance ai : classInfo.annotations()) {
    builder(ai, MyAnno.class); // may pass foreign annotations
}
// after
for (AnnotationInstance ai : classInfo.annotations(DotName.createSimple(MyAnno.class.getName()))) {
    builder(ai, MyAnno.class);
}

if (!ai.name().toString().equals(MyAnno.class.getName())) {
    throw new IllegalArgumentException("wrong annotation: " + ai.name());
}

When it happens

Trigger: Calling AnnotationProxyProvider.builder(annotationInstance, SomeAnnotation.class) where annotationInstance.name() does not equal SomeAnnotation's fully qualified name — typically a lookup-by-name/predicate returned instances of other annotations mixed in with the target.

Common situations: Build steps scanning all annotations of a class and passing them to the proxy provider without filtering by name; iterating a Jandex index with a loose name prefix match.

Related errors

• Unknown value of annotation member ${name}
• Method ${method} not implemented
• The configuration ${clazz} is missing the @ConfigRoot annota
• Failed to process ${path}
• Failed to index: ${name}

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