{"record":{"id":"73a45b198b2d541c","repo":"hibernate/hibernate-orm","slug":"is-not-an-entity","errorCode":null,"errorMessage":"{} is not an entity","messagePattern":"(.+?) is not an entity","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/jpa/internal/PersistenceUnitUtilImpl.java","lineNumber":149,"sourceCode":"\t\t}\n\t}\n\n\tprivate Object getIdentifierFromPersister(Object entity) {\n\t\treturn getPersister( entity ).getIdentifier( entity );\n\t}\n\n\tprivate Object getVersionFromPersister(Object entity) {\n\t\treturn getPersister( entity ).getVersion( entity );\n\t}\n\n\tprivate EntityPersister getPersister(Object entity) {\n\t\tfinal var entityClass = Hibernate.getClass( entity );\n\t\ttry {\n\t\t\tfinal var entityPersister =\n\t\t\t\t\tsessionFactory.getMappingMetamodel()\n\t\t\t\t\t\t\t.getEntityDescriptor( entityClass );\n\t\t\tif ( entityPersister == null ) {\n\t\t\t\tthrow new IllegalArgumentException( entityClass.getName() + \" is not an entity\" );\n\t\t\t}\n\t\t\treturn entityPersister;\n\t\t}\n\t\tcatch (MappingException ex) {\n\t\t\tthrow new IllegalArgumentException( entityClass.getName() + \" is not an entity\", ex );\n\t\t}\n\t}\n\n}\n","sourceCodeStart":131,"sourceCodeEnd":159,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/jpa/internal/PersistenceUnitUtilImpl.java#L131-L159","documentation":"Thrown by PersistenceUnitUtilImpl.getPersister() as an IllegalArgumentException when theSessionFactory's mapping metamodel has no EntityPersister for the given class - i.e. the object passed to PersistenceUnitUtil.getIdentifier()/getVersion() is an instance of a class that is not a mapped entity in this persistence unit. Both the null-persister check and any MappingException during lookup are wrapped in this error.","triggerScenarios":"Calling getIdentifier()/getVersion() on a DTO, a plain POJO, a class mapped in a different SessionFactory, or an entity class whose mapping was never added (e.g. not listed in persistence.xml when <exclude-unlisted-classes>true</exclude-unlisted-classes>).","commonSituations":"Passing projections/DTOs from query results into JPA metadata helpers; multi-persistence-unit apps where the wrong EntityManagerFactory is used; entities living in a jar not scanned because unlisted classes are excluded; test fixtures instantiating unmapped copies of entity classes.","solutions":["Register the class as an entity in the persistence unit (@Entity plus discoverable via scanning or listed in persistence.xml).","Make sure you call the PersistenceUnitUtil of the EntityManagerFactory that actually maps that class.","If you pass DTOs, do not route them through getIdentifier/getVersion - carry the id in the DTO explicitly.","With exclude-unlisted-classes=true, add a <class> entry for every entity."],"exampleFix":"<!-- before -->\n<persistence-unit name=\"pu\">\n  <exclude-unlisted-classes>true</exclude-unlisted-classes>\n  <!-- com.acme.Order missing -> getIdentifier(order) throws 'is not an entity' -->\n</persistence-unit>\n\n<!-- after -->\n<persistence-unit name=\"pu\">\n  <exclude-unlisted-classes>true</exclude-unlisted-classes>\n  <class>com.acme.Order</class>\n</persistence-unit>","handlingStrategy":"type-guard","validationCode":"// guard before calling PersistenceUnitUtil\nif (!emf.getMetamodel().getEntities().stream()\n        .map(e -> e.getJavaType())\n        .anyMatch(t -> t.isAssignableFrom(entity.getClass()))) {\n    throw new IllegalArgumentException(entity.getClass() + \" is not mapped in this persistence unit\");\n}","typeGuard":"boolean isMappedEntity(EntityManagerFactory emf, Class<?> type) {\n    try { return emf.getMetamodel().entity(type) != null; }\n    catch (IllegalArgumentException e) { return false; }\n}","tryCatchPattern":null,"preventionTips":["Route only real entities through getIdentifier/getVersion; keep ids inside DTOs explicitly.","With exclude-unlisted-classes=true, add a <class> entry per entity and test boot of every unit.","In multi-PU apps, key PersistenceUnitUtil lookups by the same name as the EntityManagerFactory."],"tags":["hibernate","jpa","entity-mapping","persistence-unit-util","unmapped-class"],"backgroundTag":"entity-not-managed","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}