quarkusio/quarkus · error · IllegalArgumentException

Currently only Entities with the @Id or @EmbeddedId annotati

Error message

Currently only Entities with the @Id or @EmbeddedId annotation are supported. Offending class is ${entity}

What it means

The Spring Data JPA extension requires every repository entity to expose an identifier annotated with @Id or @EmbeddedId so it can generate save/finder implementations. If neither annotation is found on the entity nor any of its superclasses (i.e., the hierarchy bottoms out at java.lang.Object without an id annotation), the build fails with this IllegalArgumentException.

Source

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

    private AnnotationTarget getIdAnnotationTarget(DotName entityDotName, IndexView index) {
        return getIdAnnotationTargetRec(entityDotName, index, entityDotName);
    }

    private AnnotationTarget getIdAnnotationTargetRec(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");
        }

        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);
    }

View on GitHub (pinned to e1c734241f)

Solutions

  1. Annotate the identifier field or getter with jakarta.persistence.@Id (or @EmbeddedId for embedded ids)
  2. If the id lives in a superclass, ensure the superclass is actually in the hierarchy being compiled (right import/dependency)
  3. Verify the annotation import is jakarta.persistence.Id, not a similarly named custom annotation
  4. For composite keys, use @EmbeddedId with an @Embeddable key class

Example fix

// before
@Entity
public class User {
    private Long id; // no annotation
}

// after
@Entity
public class User {
    @Id
    private Long id;
}
Defensive patterns

Strategy: validation

Validate before calling

// Pre-check in a unit test:
assertTrue(java.lang.reflect.Field.class.isAssignableFrom(User.class.getDeclaredFields().length > 0
    && java.util.Arrays.stream(User.class.getDeclaredFields())
        .anyMatch(f -> f.isAnnotationPresent(jakarta.persistence.Id.class)
            || f.isAnnotationPresent(jakarta.persistence.EmbeddedId.class)));

Prevention

When it happens

Trigger: An entity class reachable from a Spring Data repository has no @Id or @EmbeddedId on any field or getter anywhere in its class hierarchy; the id annotation is a custom/non-JPA annotation the extension doesn't recognize.

Common situations: Using a custom @Key or Lombok-only id; forgetting @Id after copying an entity; using jakarta.persistence vs javax.persistence mismatch so the annotation isn't the JPA one the extension looks up.

Related errors

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