{"record":{"id":"e91fe86263288ca9","repo":"quarkusio/quarkus","slug":"you-can-only-annotate-one-field-or-method-with","errorCode":null,"errorMessage":"You can only annotate one field or method with @${annotation}","messagePattern":"You can only annotate one field or method with @(.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"extensions/security-jpa-common/deployment/src/main/java/io/quarkus/security/jpa/common/deployment/JpaSecurityIdentityUtil.java","lineNumber":135,"sourceCode":"            trueBranch.returnNull();\n        });\n        // Builder builder = JpaIdentityProviderUtil.trusted(request);\n        Expr builder = bc.invokeStatic(MethodDesc.of(JpaIdentityProviderUtil.class,\n                \"trusted\",\n                QuarkusSecurityIdentity.Builder.class,\n                TrustedAuthenticationRequest.class),\n                requestParam);\n        LocalVar builderVar = bc.localVar(\"builder\", QuarkusSecurityIdentity.Builder.class, builder);\n\n        setupRoles(index, jpaSecurityDefinition, panacheEntityPredicate, userVar, builderVar, bc);\n    }\n\n    static AnnotationTarget getSingleAnnotatedElement(Index index, DotName annotation) {\n        List<AnnotationInstance> annotations = index.getAnnotations(annotation);\n        if (annotations.isEmpty()) {\n            return null;\n        } else if (annotations.size() > 1) {\n            throw new RuntimeException(\"You can only annotate one field or method with @\" + annotation);\n        }\n        return annotations.get(0).target();\n    }\n\n    private static void setupRoles(Index index, JpaSecurityDefinition jpaSecurityDefinition,\n            PanacheEntityPredicateBuildItem panacheEntityPredicate, Expr userVar,\n            LocalVar builderVar, BlockCreator bc) {\n        Expr role = jpaSecurityDefinition.roles.readValue(bc, userVar);\n        // role: user.getRole()\n        boolean handledRole = false;\n        Type rolesType = jpaSecurityDefinition.roles.type();\n        switch (rolesType.kind()) {\n            case ARRAY:\n                // FIXME: support non-JPA-backed array roles?\n                break;\n            case CLASS:\n                if (rolesType.name().equals(DotNames.STRING)) {\n                    // JpaIdentityProviderUtil.addRoles(builder, :role)","sourceCodeStart":117,"sourceCodeEnd":153,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/security-jpa-common/deployment/src/main/java/io/quarkus/security/jpa/common/deployment/JpaSecurityIdentityUtil.java#L117-L153","documentation":"The JPA security extension expects exactly one element in the application indexed by Jandex to carry a given annotation (such as @Username, @Password, or @Roles). If more than one field or method carries that annotation, the build-time generator cannot decide which one to use and aborts the build.","triggerScenarios":"Declaring @Username, @Password, or @Roles on more than one field or getter — across all classes in the application index, not just within one entity — then building the application with a @UserDefinition entity present.","commonSituations":"Having a @UserDefinition entity plus another class (e.g. an admin entity or DTO) also annotated with @Roles or @Username; leftover annotations after refactoring; multiple user entity candidates kept around 'temporarily'.","solutions":["Keep the annotation on exactly one field or method in the whole application; remove duplicate @Username/@Password/@Roles annotations.","If you need multiple user representations, annotate only the @UserDefinition entity and remove annotations from other classes.","Move duplicate annotations into plain fields (no security annotations) if they are used for non-authentication purposes."],"exampleFix":"// before: two annotated classes\n@UserDefinition public class User { @Roles public String role; }\npublic class AdminUser { @Roles public String role; }\n\n// after\n@UserDefinition public class User { @Roles public String role; }\npublic class AdminUser { public String role; }","handlingStrategy":"validation","validationCode":"// before build: ensure single occurrence of each security annotation\nlong count = Stream.of(entityClasses)\n    .flatMap(c -> Arrays.stream(c.getDeclaredFields()))\n    .filter(f -> f.isAnnotationPresent(Username.class))\n    .count();\nif (count > 1) throw new IllegalStateException(\"@Username must appear on exactly one member\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Annotate security members only on the single @UserDefinition entity.","Search the codebase for @Username/@Password/@Roles before adding new ones.","Remove leftover annotations after refactors."],"tags":["quarkus","security-jpa","build-time","jandex","duplicate-annotation"],"backgroundTag":"duplicate-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"}