{"record":{"id":"983a3c19b616a7f7","repo":"quarkusio/quarkus","slug":"annotation-is-not-a-registered-qualifier-annota","errorCode":null,"errorMessage":"Annotation is not a registered qualifier: ${annotationType}","messagePattern":"Annotation is not a registered qualifier: (.+?)","errorType":"exception","errorClass":"java.lang.IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"independent-projects/arc/runtime/src/main/java/io/quarkus/arc/impl/Qualifiers.java","lineNumber":154,"sourceCode":"                return false;\n            }\n        }\n        return true;\n    }\n\n    private static Object invoke(Method method, Object instance) {\n        try {\n            method.setAccessible(true);\n            return method.invoke(instance);\n        } catch (IllegalArgumentException | IllegalAccessException | InvocationTargetException e) {\n            throw new RuntimeException(\n                    \"Error checking value of member method \" + method.getName() + \" on \" + method.getDeclaringClass(), e);\n        }\n    }\n\n    private void verifyQualifier(Class<? extends Annotation> annotationType) {\n        if (!allQualifiers.contains(annotationType.getName())) {\n            throw new IllegalArgumentException(\"Annotation is not a registered qualifier: \" + annotationType);\n        }\n    }\n\n    private static class TimesSeenBiFunction implements BiFunction<Class<? extends Annotation>, Integer, Integer> {\n\n        private static final TimesSeenBiFunction INSTANCE = new TimesSeenBiFunction();\n\n        private TimesSeenBiFunction() {\n        }\n\n        @Override\n        public Integer apply(Class<? extends Annotation> k, Integer v) {\n            return (v == null) ? 1 : (v + 1);\n        }\n    }\n}\n","sourceCodeStart":136,"sourceCodeEnd":171,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/independent-projects/arc/runtime/src/main/java/io/quarkus/arc/impl/Qualifiers.java#L136-L171","documentation":"Qualifiers.verify() checks that every annotation passed to qualifier-matching APIs is one of the qualifiers registered in the container's deployment. If annotationType is not in allQualifiers, IllegalArgumentException is thrown. This catches lookups using annotations that were never declared as CDI qualifiers.","triggerScenarios":"Passing a plain (non-@Qualifier) annotation, or a qualifier from a library not part of the indexed deployment, into Arc.container().instance()/select() or Instance.select(...) as a qualifier argument.","commonSituations":"Typos or a forgotten @Qualifier meta-annotation on a custom annotation; using an annotation from a module not indexed by Jandex; lookups written against a qualifier that was removed/renamed in an upgrade.","solutions":["Add @jakarta.inject.Qualifier (with @Retention(RUNTIME)) to the annotation type and rebuild so it's indexed.","Ensure the annotation's package is part of the indexed application/extension (Jandex index present).","Check the annotation name — you may be using a similarly named non-qualifier annotation by mistake.","After upgrading a library, verify the qualifier still exists and is registered; update the lookup accordingly."],"exampleFix":"// before\n@Retention(RUNTIME)\npublic @interface Cool { } // missing @Qualifier\n// after\n@Qualifier\n@Retention(RUNTIME)\npublic @interface Cool { }","handlingStrategy":"validation","validationCode":"static void requireQualifier(Class<? extends Annotation> a) {\n    if (!a.isAnnotationPresent(jakarta.inject.Qualifier.class)) {\n        throw new IllegalArgumentException(a + \" is missing @Qualifier; it cannot be used in select()\");\n    }\n}","typeGuard":"boolean isCdiQualifier(Class<? extends Annotation> a) {\n    return a.isAnnotationPresent(jakarta.inject.Qualifier.class);\n}","tryCatchPattern":"try {\n    return Arc.container().instance(type, qualifier);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().startsWith(\"Annotation is not a registered qualifier\")) {\n        throw new IllegalStateException(\"Add @Qualifier to \" + qualifier.annotationType() + \" and rebuild\", e);\n    }\n    throw e;\n}","preventionTips":["Meta-annotate every custom lookup annotation with @Qualifier","Verify the annotation's module is indexed by Jandex","After library upgrades, confirm qualifiers still exist before lookup","Catch typos early by centralizing qualifier literals in one place"],"tags":["cdi","qualifier","arc","jandex"],"backgroundTag":"unregistered-qualifier-annotation","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}