What causes "Unknown entity type '{}'" in hibernate/hibernate-orm?

Use the registered entity name: default is the unqualified class name, otherwise the @Entity(name=...) value

hibernate/hibernate-orm · error · UnknownEntityTypeException

Unknown entity type '{}'

Error message

Unknown entity type '{}'

What it means

MappingMetamodelImpl.getEntityDescriptor(String) looks the persister up by JPA entity name in entityPersisterMap; a miss throws UnknownEntityTypeException with the given name. This backs every name-based runtime API: HQL 'from X', session.get("X", id), loaders, filters, and cache APIs.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/internal/MappingMetamodelImpl.java:350

		return this;
	}

	public ServiceRegistry getServiceRegistry() {
		return jpaMetamodel.getServiceRegistry();
	}

	@Override
	public void forEachEntityDescriptor(Consumer<EntityPersister> action) {
		for ( var value : entityPersisterMap.values() ) {
			action.accept( value );
		}
	}

	@Override
	public EntityPersister getEntityDescriptor(String entityName) {
		final var entityPersister = entityPersisterMap.get( entityName );
		if ( entityPersister == null ) {
			throw new UnknownEntityTypeException( entityName );
		}
		return entityPersister;
	}

	@Override
	public EntityPersister getEntityDescriptor(NavigableRole name) {
		throw new UnsupportedOperationException();
	}

	@Override
	public EmbeddableValuedModelPart getEmbeddableValuedModelPart(NavigableRole role){
		final var embeddableMappingType = embeddableValuedModelPart.get( role );
		if ( embeddableMappingType == null ) {
			throw new IllegalArgumentException( "Unable to locate EmbeddableValuedModelPart: " + role );
		}
		return embeddableMappingType;
	}

View on GitHub (pinned to fad1729dce)

Solutions

Use the registered entity name: default is the unqualified class name, otherwise the @Entity(name=...) value
List the actual names from the metamodel and compare: emf.getMetamodel().getEntities().forEach(e -> System.out.println(e.getName()))
Prefer the class-based variants (session.find(Class, id), typed HQL) so names are checked at compile time

Example fix

// before
Object o = session.get("com.acme.Customer", 1L); // UnknownEntityTypeException

// after
@Entity(name = "CUST") public class Customer {...}
Object o = session.get("CUST", 1L);
// or, compile-safe:
Customer c = session.get(Customer.class, 1L);

Defensive patterns

Strategy: validation

Validate before calling

Set<String> entityNames = emf.getMetamodel().getEntities().stream()
    .map(EntityType::getName)
    .collect(Collectors.toSet());
if (!entityNames.contains(entityName)) {
  throw new IllegalArgumentException(
      "No entity named '" + entityName + "'. Registered names: " + entityNames);
}
Object o = session.get(entityName, id); // safe now

Try / catch

try {
  Object o = session.get(entityName, id);
} catch (UnknownEntityTypeException e) {
  // log registered names to pinpoint the mismatch
  throw new IllegalArgumentException("Unknown entity name '" + entityName
      + "'; known: " + emf.getMetamodel().getEntities().stream().map(EntityType::getName).toList(), e);
}

Prevention

Prefer class-based lookups (session.get(Class, id)) and typed HQL so entity names are compile-checked
Centralize entity-name strings as constants derived from @Entity(name=...) values
When you must use string names, validate against the metamodel name set once at startup

When it happens

Trigger: session.get("Customer", id) or HQL 'from Customer' where the entity is registered under a different name; using the fully-qualified class name when the default registration is the unqualified name; typo or case mismatch in the entity name string.

Common situations: @Entity(name="CUST") renames that leave stale string references in queries/code; teams assuming FQN is accepted; names copied from a different persistence unit or module; string-based loaders in configuration files drifting from the mapping.

Related errors

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