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(Class) looks up the persistence unit name for the given class in the build-time-generated entityToPersistenceUnit map. If the class is absent, it throws IllegalStateException: the class was never registered as a Hibernate entity for a Quarkus-configured PU, which almost always means it isn't a real @Entity.

Source

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

    }

    public Uni<Integer> update(Class<?> entityClass, String query, Object... params) {
        return executeUpdate(entityClass, query, params);
    }

    //
    // Static helpers

    public Uni<SessionType> getSession() {
        return getSession(DEFAULT_PERSISTENCE_UNIT_NAME);
    }

    public Uni<SessionType> getSession(Class<?> clazz) {
        String className = clazz.getName();
        String persistenceUnitName = entityToPersistenceUnit.get(className);
        if (persistenceUnitName == null) {
            // 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'?",
                    clazz));
        }
        return getSession(persistenceUnitName);
    }

    public Uni<SessionType> getSession(String persistenceUnitName) {
        return sessionType == Mutiny.Session.class ? (Uni<SessionType>) SessionOperations.getSession(persistenceUnitName)
                : (Uni<SessionType>) SessionOperations.getStatelessSession(persistenceUnitName);
    }

    public static Mutiny.Query<?> bindParameters(Mutiny.Query<?> query, Object[] params) {
        if (params == null || params.length == 0)
            return query;
        for (int i = 0; i < params.length; i++) {
            query.setParameter(i + 1, params[i]);
        }
        return query;

View on GitHub (pinned to e1c734241f)

Solutions

Annotate the class with jakarta.persistence.@Entity (and extend PanacheEntity/PanacheRepository as appropriate)
Ensure the entity's package is covered by the active persistence unit's scan configuration (quarkus.hibernate-orm.packages)
Check you passed the entity class, not a DTO/projection class
Rebuild after adding the entity so the entity-to-PU map is regenerated

Example fix

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

Defensive patterns

Strategy: type-guard

Validate before calling

String pu = entityToPersistenceUnit(entityClass);
if (pu == null)
    throw new IllegalStateException("Class " + entityClass + " is not a registered @Entity in any persistence unit");

Type guard

static boolean isPanacheEntity(Class<?> c) {
    for (Class<?> k = c; k != null && k != Object.class; k = k.getSuperclass())
        if (k.isAnnotationPresent(jakarta.persistence.Entity.class)) return true;
    return false;
}

Try / catch

try {
    return operations.getSession(EntityClass.class);
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().contains("was not found")) {
        throw new IllegalStateException("Did you forget @Entity on " + EntityClass.getSimpleName() + "?", e);
    }
    throw e;
}

Prevention

Annotate every Panache entity with @Entity
Keep entities inside packages scanned by the configured persistence unit
Avoid passing DTOs or projection classes to Panache operations
Rebuild after adding entities so the entity-to-PU map refreshes

When it happens

Trigger: Calling Panache operations (persist/find/...) on a class not annotated with @Entity, or on an entity outside all configured persistence units; class not in the scanned packages of any PU.

Common situations: Forgetting @Entity on a PanacheEntity subclass; passing a DTO or non-entity class to PanacheQuery operations; entity in a package excluded from quarkus.hibernate-orm packages config; testing with a mock entity.

Related errors

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