What causes "Entity '{entityName}' is not a dynamic entity" in hibernate/hibernate-orm?

For normal annotated classes use createGraph(Class) or createGraph(String) instead — the non-dynamic EntityGraph API

hibernate/hibernate-orm · error · IllegalArgumentException

Entity '{entityName}' is not a dynamic entity

Error message

Entity '{entityName}' is not a dynamic entity

What it means

createGraphForDynamicEntity() builds an EntityGraph over a dynamic (Map-based) entity, i.e. one mapped with RepresentationMode.MAP where attribute values live in a java.util.Map rather than a POJO. If the named entity is a normal annotated POJO entity, the representation check fails and IllegalArgumentException is thrown. The method is the dynamic-model counterpart of the typed createGraph(Class) API.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/internal/SessionFactoryImpl.java:988

	@Override
	@Nonnull
	public MappingMetamodel getMetamodel() {
		validateNotClosed();
		return runtimeMetamodels.getMappingMetamodel();
	}

	@Override
	public boolean isOpen() {
		return status != Status.CLOSED;
	}

	@Override
	@Nonnull
	public RootGraphImplementor<Map<String, ?>> createGraphForDynamicEntity(@Nonnull String entityName) {
		final var entity = getJpaMetamodel().entity( entityName );
		if ( entity.getRepresentationMode() != RepresentationMode.MAP ) {
			throw new IllegalArgumentException( "Entity '" + entityName + "' is not a dynamic entity" );
		}
		@SuppressWarnings("unchecked") //Safe, because we just checked
		final var dynamicEntity = (EntityDomainType<Map<String, ?>>) entity;
		return new RootGraphImpl<>( null, dynamicEntity );
	}

	@Override
	@Nullable
	public RootGraphImplementor<?> findEntityGraphByName(@Nonnull String name) {
		return getJpaMetamodel().findEntityGraphByName( name );
	}

	@Override
	@Nullable
	public String bestGuessEntityName(@Nonnull Object object) {
		final var initializer = extractLazyInitializer( object );
		if ( initializer != null ) {
			// it is possible for this method to be called during flush processing,

View on GitHub (pinned to fad1729dce)

Solutions

For normal annotated classes use createGraph(Class) or createGraph(String) instead — the non-dynamic EntityGraph API
If you genuinely want dynamic entities, map them with Map representation (hbm.xml entity-mode="map" / dynamic-map mappings) so RepresentationMode is MAP
Check the representation before calling: metamodel.entity(name).getRepresentationMode() == RepresentationMode.MAP
Verify the entityName string matches a mapped entity; misspelled names usually surface as UnknownEntityTypeException first

Example fix

// before
RootGraph<Map<String, ?>> graph =
        sessionFactory.createGraphForDynamicEntity("Order"); // Order is a POJO @Entity

// after
@Nullable RootGraphImplementor<Order> orderGraph =
        sessionFactory.createGraph(Order.class);

Defensive patterns

Strategy: validation

Validate before calling

// JPA metamodel does not expose representation mode; guard by trying the typed API first
EntityDomainType<?> type = sessionFactory.getJpaMetamodel()
        .getEntities().stream()
        .filter(e -> e.getName().equals(entityName))
        .findFirst().orElseThrow();
// If you own the mapping: only call createGraphForDynamicEntity for Map-based mappings

Try / catch

try {
    return sessionFactory.createGraphForDynamicEntity(name);
} catch (IllegalArgumentException e) {
    // Not a Map-representation entity: fall back to the typed graph API
    return sessionFactory.createGraph(entityClass); // or createGraph(name)
}

Prevention

Default to createGraph(Class)/entityGraph APIs; reserve createGraphForDynamicEntity for genuine dynamic-map mappings
Document in your codebase which entities (if any) use RepresentationMode.MAP
Add a startup smoke test that builds graphs for every entity name you will use at runtime

When it happens

Trigger: Calling sessionFactory.createGraphForDynamicEntity("Order") where Order is an @Entity POJO class (RepresentationMode.POJO) instead of a Map-mode dynamic entity. Also passing a subclass or entity name whose mapping uses anything other than MAP representation.

Common situations: Code written against Hibernate's legacy dynamic-map ('entity mode map') model reused with POJO mappings; generic/framework code that always uses the dynamic variant of graph creation; exploratory use of the new graph API without realizing the dynamic/entity split.

Related errors

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