hibernate/hibernate-orm · error · UnknownEntityTypeException

Unknown entity type '" + entityClass.getName() + "'

Error message

Unknown entity type '" + entityClass.getName() + "'

What it means

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>').

Source

Thrown at hibernate-core/src/main/java/org/hibernate/Hibernate.java:445

	 * by calling {@link #initialize(Object)}. It can be used to represent a reference to
	 * the entity when working with a detached object graph.
	 *
	 * @param sessionFactory the session factory with which the entity is associated
	 * @param entityClass the entity class
	 * @param id the id of the persistent entity instance
	 *
	 * @return a detached uninitialized proxy
	 *
	 * @since 6.0
	 */
	@SuppressWarnings("unchecked")
	public static <E> E createDetachedProxy(SessionFactory sessionFactory, Class<E> entityClass, Object id) {
		final var persister =
				sessionFactory.unwrap( SessionFactoryImplementor.class )
						.getMappingMetamodel()
						.findEntityDescriptor( entityClass );
		if ( persister == null ) {
			throw new UnknownEntityTypeException( entityClass );
		}
		return (E) persister.createProxy( id, null );
	}

	/**
	 * Operations for obtaining references to persistent collections of a certain type.
	 *
	 * @param <C> the type of collection, for example, {@code List&lt;User&gt;}
	 *
	 * @since 6.0
	 */
	public static final class CollectionInterface<C> {
		private final Supplier<C> detached;
		private final Supplier<C> created;

		private CollectionInterface(Supplier<C> detached, Supplier<C> created) {
			this.detached = detached;
			this.created = created;

View on GitHub (pinned to fad1729dce)

Solutions

1. Verify entityClass is a registered entity of that factory: check sessionFactory.getMetamodel().getEntities() contains it.
2. Pass the SessionFactory built from the persistence unit that actually maps the class.
3. If you passed a superclass or @MappedSuperclass, pass the concrete @Entity subclass instead.
4. For reference proxies inside a session, use session.getReference()/em.getReference() which gives clearer errors.

Example fix

// before - Animal is a @MappedSuperclass, not an entity
Dog proxy = Hibernate.createDetachedProxy(sf, Animal.class, 42L);

// after - concrete mapped entity
Dog proxy = Hibernate.createDetachedProxy(sf, Dog.class, 42L);

static <E> boolean isMappedEntity(SessionFactory sf, Class<E> type) {
    return sf.getMetamodel().getEntities().stream()
            .anyMatch(et -> et.getJavaType() == type);
}

if (!isMappedEntity(sf, entityClass)) {
    throw new IllegalArgumentException("Not a mapped entity in this factory: " + entityClass.getName());
}
E proxy = Hibernate.createDetachedProxy(sf, entityClass, id);

static <E> boolean isMappedEntity(SessionFactory sf, Class<E> type) {
    return sf.getMetamodel().getEntities().stream()
            .anyMatch(et -> et.getJavaType() == type);
}

try {
    return Hibernate.createDetachedProxy(sf, entityClass, id);
} catch (UnknownEntityTypeException e) {
    throw new IllegalArgumentException(
        entityClass.getName() + " is not mapped by the given SessionFactory", e);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unable to build Hibernate SessionFactory [persistence unit:
• An association from the table '" + getTable().getName() + "'
• entity class not found: " + className
• proxy class not found: " + proxyInterfaceName
• proxy must be either an interface, or the class itself: {}

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/fcf86eed688dd86f. Report an issue: GitHub.