{"record":{"id":"000c7012f744ff83","repo":"quarkusio/quarkus","slug":"entity-s-was-not-found-did-you-forget-to-annot-000c70","errorCode":null,"errorMessage":"Entity '%s' was not found. Did you forget to annotate your Panache Entity classes with '@Entity'?","messagePattern":"Entity '(.+?)' was not found\\. Did you forget to annotate your Panache Entity classes with '@Entity'\\?","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/panache/hibernate-reactive-panache-common/runtime/src/main/java/io/quarkus/hibernate/reactive/panache/common/runtime/AbstractJpaOperations.java","lineNumber":362,"sourceCode":"    }\n\n    public Uni<Integer> update(Class<?> entityClass, String query, Object... params) {\n        return executeUpdate(entityClass, query, params);\n    }\n\n    //\n    // Static helpers\n\n    public Uni<SessionType> getSession() {\n        return getSession(DEFAULT_PERSISTENCE_UNIT_NAME);\n    }\n\n    public Uni<SessionType> getSession(Class<?> clazz) {\n        String className = clazz.getName();\n        String persistenceUnitName = entityToPersistenceUnit.get(className);\n        if (persistenceUnitName == null) {\n            // For Quarkus-configured PUs, or if there is no PU, this is definitely an error.\n            throw new IllegalStateException(String.format(\n                    \"Entity '%s' was not found. Did you forget to annotate your Panache Entity classes with '@Entity'?\",\n                    clazz));\n        }\n        return getSession(persistenceUnitName);\n    }\n\n    public Uni<SessionType> getSession(String persistenceUnitName) {\n        return sessionType == Mutiny.Session.class ? (Uni<SessionType>) SessionOperations.getSession(persistenceUnitName)\n                : (Uni<SessionType>) SessionOperations.getStatelessSession(persistenceUnitName);\n    }\n\n    public static Mutiny.Query<?> bindParameters(Mutiny.Query<?> query, Object[] params) {\n        if (params == null || params.length == 0)\n            return query;\n        for (int i = 0; i < params.length; i++) {\n            query.setParameter(i + 1, params[i]);\n        }\n        return query;","sourceCodeStart":344,"sourceCodeEnd":380,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/panache/hibernate-reactive-panache-common/runtime/src/main/java/io/quarkus/hibernate/reactive/panache/common/runtime/AbstractJpaOperations.java#L344-L380","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\npublic class Person extends PanacheEntity { public String name; }\n// after\n@Entity\npublic class Person extends PanacheEntity { public String name; }","handlingStrategy":"type-guard","validationCode":"String pu = entityToPersistenceUnit(entityClass);\nif (pu == null)\n    throw new IllegalStateException(\"Class \" + entityClass + \" is not a registered @Entity in any persistence unit\");","typeGuard":"static boolean isPanacheEntity(Class<?> c) {\n    for (Class<?> k = c; k != null && k != Object.class; k = k.getSuperclass())\n        if (k.isAnnotationPresent(jakarta.persistence.Entity.class)) return true;\n    return false;\n}","tryCatchPattern":"try {\n    return operations.getSession(EntityClass.class);\n} catch (IllegalStateException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"was not found\")) {\n        throw new IllegalStateException(\"Did you forget @Entity on \" + EntityClass.getSimpleName() + \"?\", e);\n    }\n    throw e;\n}","preventionTips":["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"],"tags":["quarkus","panache","hibernate-reactive","entity","persistence-unit"],"backgroundTag":"entity-not-annotated","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}