{"record":{"id":"fcf86eed688dd86f","repo":"hibernate/hibernate-orm","slug":"unknown-entity-type-entityclass-getname","errorCode":null,"errorMessage":"Unknown entity type '\" + entityClass.getName() + \"'","messagePattern":"Unknown entity type '\" \\+ entityClass\\.getName\\(\\) \\+ \"'","errorType":"exception","errorClass":"UnknownEntityTypeException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/Hibernate.java","lineNumber":445,"sourceCode":"\t * by calling {@link #initialize(Object)}. It can be used to represent a reference to\n\t * the entity when working with a detached object graph.\n\t *\n\t * @param sessionFactory the session factory with which the entity is associated\n\t * @param entityClass the entity class\n\t * @param id the id of the persistent entity instance\n\t *\n\t * @return a detached uninitialized proxy\n\t *\n\t * @since 6.0\n\t */\n\t@SuppressWarnings(\"unchecked\")\n\tpublic static <E> E createDetachedProxy(SessionFactory sessionFactory, Class<E> entityClass, Object id) {\n\t\tfinal var persister =\n\t\t\t\tsessionFactory.unwrap( SessionFactoryImplementor.class )\n\t\t\t\t\t\t.getMappingMetamodel()\n\t\t\t\t\t\t.findEntityDescriptor( entityClass );\n\t\tif ( persister == null ) {\n\t\t\tthrow new UnknownEntityTypeException( entityClass );\n\t\t}\n\t\treturn (E) persister.createProxy( id, null );\n\t}\n\n\t/**\n\t * Operations for obtaining references to persistent collections of a certain type.\n\t *\n\t * @param <C> the type of collection, for example, {@code List&lt;User&gt;}\n\t *\n\t * @since 6.0\n\t */\n\tpublic static final class CollectionInterface<C> {\n\t\tprivate final Supplier<C> detached;\n\t\tprivate final Supplier<C> created;\n\n\t\tprivate CollectionInterface(Supplier<C> detached, Supplier<C> created) {\n\t\t\tthis.detached = detached;\n\t\t\tthis.created = created;","sourceCodeStart":427,"sourceCodeEnd":463,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/Hibernate.java#L427-L463","documentation":"Hibernate.createDetachedProxy(sessionFactory, entityClass, id) creates an uninitialized proxy without a session by looking up the entity persister via findEntityDescriptor(entityClass). If the class is not a mapped entity in that exact SessionFactory, the lookup returns null and Hibernate throws UnknownEntityTypeException ('Unknown entity type: <class name>').","triggerScenarios":"Calling Hibernate.createDetachedProxy(sf, NotAnEntity.class, id); passing an @MappedSuperclass or an interface/superclass that is not itself an @Entity; passing a SessionFactory from a different persistence unit that does not contain the entity.","commonSituations":"Multi-persistence-unit applications handing in the wrong factory; generic framework code that derives the entity class dynamically (and sometimes lands on a superclass); refactoring that turns a class into a mapped superclass; test fixtures referencing an unmapped class.","solutions":["Verify entityClass is a registered entity of that factory: check sessionFactory.getMetamodel().getEntities() contains it.","Pass the SessionFactory built from the persistence unit that actually maps the class.","If you passed a superclass or @MappedSuperclass, pass the concrete @Entity subclass instead.","For reference proxies inside a session, use session.getReference()/em.getReference() which gives clearer errors."],"exampleFix":"// before - Animal is a @MappedSuperclass, not an entity\nDog proxy = Hibernate.createDetachedProxy(sf, Animal.class, 42L);\n\n// after - concrete mapped entity\nDog proxy = Hibernate.createDetachedProxy(sf, Dog.class, 42L);","handlingStrategy":"validation","validationCode":"static <E> boolean isMappedEntity(SessionFactory sf, Class<E> type) {\n    return sf.getMetamodel().getEntities().stream()\n            .anyMatch(et -> et.getJavaType() == type);\n}\n\nif (!isMappedEntity(sf, entityClass)) {\n    throw new IllegalArgumentException(\"Not a mapped entity in this factory: \" + entityClass.getName());\n}\nE proxy = Hibernate.createDetachedProxy(sf, entityClass, id);","typeGuard":"static <E> boolean isMappedEntity(SessionFactory sf, Class<E> type) {\n    return sf.getMetamodel().getEntities().stream()\n            .anyMatch(et -> et.getJavaType() == type);\n}","tryCatchPattern":"try {\n    return Hibernate.createDetachedProxy(sf, entityClass, id);\n} catch (UnknownEntityTypeException e) {\n    throw new IllegalArgumentException(\n        entityClass.getName() + \" is not mapped by the given SessionFactory\", e);\n}","preventionTips":["Pass the concrete @Entity class, never a superclass or @MappedSuperclass","In multi-PU apps, resolve the factory by the entity's persistence unit before creating proxies"],"tags":["entity","proxy","session-factory","mapping","unknown-entity"],"backgroundTag":"unknown-entity-type","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}