quarkusio/quarkus · error · IllegalArgumentException

Currently the @Id or @EmbeddedId annotation can only be plac

Error message

Currently the @Id or @EmbeddedId annotation can only be placed on a single field or method. Offending class is ${entity}

What it means

The extension supports at most one @Id or @EmbeddedId annotation per entity hierarchy when generating repository code. If more than one @Id/@EmbeddedId target is found on the entity (across fields/methods and superclasses), the build fails with this IllegalArgumentException, because the generated code would not know which attribute is the identifier.

Source

Thrown at extensions/spring-data-jpa/deployment/src/main/java/io/quarkus/spring/data/deployment/generate/StockMethodsAdder.java:1231

            throw new IllegalStateException("Entity " + originalEntityDotName + " was not part of the Quarkus index");
        }

        List<AnnotationInstance> annotationInstances = Stream.of(DotNames.JPA_ID, DotNames.JPA_EMBEDDED_ID)
                .map(classInfo.annotationsMap()::get)
                .filter(Objects::nonNull)
                .flatMap(List::stream)
                .collect(Collectors.toList());
        if (annotationInstances.isEmpty()) {
            if (DotNames.OBJECT.equals(classInfo.superName())) {
                throw new IllegalArgumentException(
                        "Currently only Entities with the @Id or @EmbeddedId annotation are supported. Offending class is "
                                + originalEntityDotName);
            }
            return getIdAnnotationTargetRec(classInfo.superName(), index, originalEntityDotName);
        }

        if (annotationInstances.size() > 1) {
            throw new IllegalArgumentException(
                    "Currently the @Id or @EmbeddedId annotation can only be placed on a single field or method. " +
                            "Offending class is " + originalEntityDotName);
        }

        return annotationInstances.get(0).target();
    }

    private Optional<AnnotationTarget> getVersionAnnotationTarget(DotName entityDotName, IndexView index) {
        return getVersionAnnotationTargetRec(entityDotName, index, entityDotName);
    }

    private Optional<AnnotationTarget> getVersionAnnotationTargetRec(DotName currentDotName, IndexView index,
            DotName originalEntityDotName) {
        ClassInfo classInfo = index.getClassByName(currentDotName);
        if (classInfo == null) {
            throw new IllegalStateException("Entity " + originalEntityDotName + " was not part of the Quarkus index");
        }

View on GitHub (pinned to e1c734241f)

Solutions

Keep exactly one @Id (or one @EmbeddedId) per entity hierarchy and remove the others
For composite keys, use a single @EmbeddedId with an @Embeddable key class, or @IdClass with a single @Id reference pattern per JPA spec
If id is defined in a superclass, delete the duplicate in the subclass
Move the annotation to the getter only, or the field only, not both

Example fix

// before
@Entity
public class User {
    @Id private Long id;
    @Id private String email; // duplicate
}

// after
@Entity
public class User {
    @Id private Long id;
    private String email;
}

Defensive patterns

Strategy: validation

Validate before calling

// Assert exactly one id annotation in the hierarchy:
long idCount = java.util.Arrays.stream(User.class.getDeclaredFields())
    .filter(f -> f.isAnnotationPresent(jakarta.persistence.Id.class)
        || f.isAnnotationPresent(jakarta.persistence.EmbeddedId.class)).count();
if (idCount != 1) throw new IllegalStateException("Entity must have exactly one @Id/@EmbeddedId");

Prevention

One @Id per hierarchy — enforce with a unit test or ArchUnit rule
Use @EmbeddedId for composite keys instead of multiple @Id
Check superclass entities before adding id fields to subclasses
Never annotate both the field and getter of the same id

When it happens

Trigger: Two fields annotated @Id in the same class; an @Id in the entity plus another @Id in a superclass; both @Id and @EmbeddedId present; @Id placed on both a field and its getter.

Common situations: Merging entity classes after refactoring; copying JPA code that used Hibernate's multiple-id support; attempting composite keys with several @Id fields instead of @EmbeddedId/@IdClass.

Related errors

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