quarkusio/quarkus · error · IllegalStateException

Entity '%s' was not found. Did you forget to annotate your P

Error message

Entity '%s' was not found. Did you forget to annotate your Panache Entity classes with '@Entity'?

What it means

getSession resolves the Hibernate session for the persistence unit that owns the given entity class by consulting the entity->PU mapping built at augmentation time. When the entity class is absent from that mapping, Panache concludes the class was never recognized as a JPA entity and throws this IllegalStateException.

Source

Thrown at extensions/panache/hibernate-orm-panache-common/runtime/src/main/java/io/quarkus/hibernate/orm/panache/common/runtime/AbstractJpaOperations.java:119

     *
     * @return {@link Session}
     */
    public SessionType getSession(Class<?> clazz) {
        String clazzName = clazz.getName();
        String persistentUnitName = entityToPersistenceUnit.get(clazzName);
        if (persistentUnitName == null) {
            if (entityToPersistenceUnitIsIncomplete == null || entityToPersistenceUnitIsIncomplete) {
                // When using persistence.xml, `entityToPersistenceUnit` is most likely empty,
                // so we'll just return the default PU and hope for the best.
                // The error will be thrown later by Hibernate ORM if necessary;
                // it will be a bit less clear, but this is an edge case.
                SessionType session = getSession(PersistenceUnitUtil.DEFAULT_PERSISTENCE_UNIT_NAME);
                if (session != null) {
                    return session;
                }
            }
            // For Quarkus-configured PUs, or if there is no PU, this is definitely an error.
            throw new IllegalStateException(String.format(
                    "Entity '%s' was not found. Did you forget to annotate your Panache Entity classes with '@Entity'?",
                    clazzName));
        }
        return getSession(persistentUnitName);
    }

    public SessionType getSession(String persistentUnitName) {
        ArcContainer arcContainer = Arc.container();
        if (persistentUnitName == null || PersistenceUnitUtil.isDefaultPersistenceUnit(persistentUnitName)) {
            return arcContainer.instance(sessionType).get();
        } else {
            return arcContainer.instance(sessionType,
                    new PersistenceUnit.PersistenceUnitLiteral(persistentUnitName))
                    .get();
        }
    }

    public SessionType getSession() {

View on GitHub (pinned to e1c734241f)

Solutions

Annotate the class with @Entity (and ensure it extends PanacheEntity or has @Id)
Verify the class is a managed JPA entity, not a DTO or base class
Ensure the entity is in a Jandex-indexed module and the app was re-built
If using multiple persistence units, confirm the entity is actually registered in one

Example fix

// before
public class Person extends PanacheEntity { }
// after
@Entity
public class Person extends PanacheEntity { }

Defensive patterns

Strategy: validation

Validate before calling

if (!clazz.isAnnotationPresent(jakarta.persistence.Entity.class)) {
    throw new IllegalArgumentException(clazz + " is not a JPA @Entity");
}

Type guard

boolean isJpaEntity(Class<?> c) {
    return c.isAnnotationPresent(jakarta.persistence.Entity.class);
}

Try / catch

try {
    Person.count();
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().contains("was not found")) {
        // add @Entity to the class and rebuild
    } else throw e;
}

Prevention

Annotate every Panache entity with @Entity
Never pass DTOs or projection classes to entity operations
Keep entities in Jandex-indexed modules
Run a clean build after adding new entities

When it happens

Trigger: Calling any Panache entity/repository operation (count, deleteAll, session(), etc.) with a class name that is not an @Entity — e.g. a DTO, an abstract base class, or a class missing the @Entity annotation.

Common situations: Forgetting @Entity on a class extending PanacheEntity; passing a projection DTO to Panache query methods; entity living in a module without Jandex indexing so the build missed it; typo in entity class name when calling getSession directly.

Related errors

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