What causes "Cannot resolve entity name : {}" in hibernate/hibernate-orm?

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

hibernate/hibernate-orm · critical · IllegalArgumentException

Cannot resolve entity name : {}

Error message

Cannot resolve entity name : {}

What it means

Thrown from the same JpaMetamodelImpl.applyNamedEntityGraphs bootstrap path, but by the name-based resolver lambda. Named entity graph definitions that reference entities by JPA entity name (XML entity graphs in orm.xml, or text/parsed graph definitions) are matched against every EntityDomainType's getName(); no match aborts startup with 'Cannot resolve entity name'.

Source

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

		for ( var definition : namedEntityGraphs ) {
			CORE_LOGGER.tracef( "Applying named entity graph [name=%s, source=%s]",
					definition.name(), definition.source() );

			final var graph = definition.graphCreator().createEntityGraph(
					entityClass -> {
						if ( managedTypeByClass.get( entityClass ) instanceof EntityDomainType<?> match ) {
							return match;
						}
						throw new IllegalArgumentException( "Cannot resolve entity class : " + entityClass.getName() );
					},
					jpaEntityName -> {
						for ( var entry : managedTypeByName.entrySet() ) {
							if ( entry.getValue() instanceof EntityDomainType<?> possibility
									&& jpaEntityName.equals( possibility.getName() ) ) {
								return possibility;
							}
						}
						throw new IllegalArgumentException( "Cannot resolve entity name : " + jpaEntityName );
					},
					serviceRegistry
			);
			entityGraphMap.put( definition.name(), graph );
		}
	}


	private Class<?> resolveRequestedClass(String entityName) {
		try {
			return classLoaderService.classForName( entityName );
		}
		catch (ClassLoadingException e) {
			return null;
		}
	}

	@Nonnull

View on GitHub (pinned to fad1729dce)

Solutions

Use the exact registered JPA entity name: default is the unqualified class name, otherwise the @Entity(name=...) value
Fix typos/casing in the entity name inside the orm.xml entity-graph or graph definition
Move the entity-graph definition into the same persistence unit as the entity it references
Prefer annotation-based @NamedEntityGraph with type references over name-based references to avoid name drift

Example fix

// before (orm.xml)
<entity-graph name="order-graph">
  <named-attribute-node name="items"/>
</entity-graph>
<!-- graph assumed for entity 'ORD' but defined on class with @Entity(name = "ORD") and referenced as 'Order' elsewhere -->

// after
@NamedQuery-less fix: reference 'ORD' wherever the graph names the entity, or rename the entity:
@Entity(name = "Order") public class Order { ... }

Defensive patterns

Strategy: validation

Validate before calling

// Compute the set of JPA entity names exactly as Hibernate registers them
Set<String> entityNames = scannedEntityClasses.stream()
    .map(c -> {
      jakarta.persistence.Entity e = c.getAnnotation(jakarta.persistence.Entity.class);
      return (e != null && !e.name().isEmpty()) ? e.name() : c.getSimpleName();
    })
    .collect(Collectors.toSet());
// Assert every entity-name reference in your graph definitions (orm.xml / parsed graphs) is contained
for (String referenced : graphReferencedNames) {
  if (!entityNames.contains(referenced)) {
    throw new IllegalStateException("Graph references unknown entity name '" + referenced + "'; known: " + entityNames);
  }
}

Try / catch

try {
  emf = Persistence.createEntityManagerFactory(puName);
} catch (RuntimeException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Cannot resolve entity name")) {
    throw new IllegalStateException("Entity graph references an unregistered entity name: " + e.getMessage(), e);
  }
  throw e;
}

Prevention

Remember entity names default to the UNQUALIFIED class name — never use fully-qualified names in graphs
When renaming via @Entity(name=...), update every XML/text graph definition in the same commit
Prefer annotation-based graphs with type references over name-based references where possible

When it happens

Trigger: An orm.xml <entity-graph> or text graph definition naming an entity that is not mapped (typo, wrong case); renaming an entity via @Entity(name="X") while the graph still uses the old/unqualified class name; a graph definition referencing an entity registered in a different persistence unit.

Common situations: Default entity name is the unqualified class name — code that assumes the fully-qualified name fails; @Entity(name=...) rename refactors miss graph definitions in XML; merging modules moves an entity to a new PU but leaves its graph behind.

Related errors

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