hibernate/hibernate-orm · error · HibernateException

Could not determine type of dynamic map entity

Error message

Could not determine type of dynamic map entity

What it means

Thrown by EntityInstantiatorDynamicMap.extractEmbeddedEntityName when the argument map is null. Dynamic-map entity support represents entities as HashMaps tagged with the '$type$' key (AbstractDynamicMapInstantiator.TYPE_KEY); the static helper rejects a null map up front because no entity name can be derived from it. In practice this line is reached through the ENTITY_NAME_RESOLVER path or internal calls that pass an already-unwrapped null, and it signals that a null was supplied where a dynamic-map entity instance was required.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/metamodel/internal/EntityInstantiatorDynamicMap.java:55

	public Object instantiate() {
		return generateDataMap();
	}

	@Override
	protected boolean isSameRole(String type) {
		return super.isSameRole( type ) || isPartOfHierarchy( type );
	}

	private boolean isPartOfHierarchy(String type) {
		return entityRoleNames.contains( type );
	}

	public static final EntityNameResolver ENTITY_NAME_RESOLVER =
			entity -> entity instanceof Map<?, ?> map ? extractEmbeddedEntityName( map ) : null;

	public static String extractEmbeddedEntityName(Map<?,?> entity) {
		if ( entity == null ) {
			throw new HibernateException( "Could not determine type of dynamic map entity" );
		}
		else {
			final String entityName = (String) entity.get( TYPE_KEY );
			if ( entityName == null ) {
				throw new HibernateException( "Could not determine type of dynamic map entity" );
			}
			return entityName;
		}
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

1. Null-check map arguments before calling session operations like merge/save/update on dynamic-map entities
2. If the value may legitimately be absent, branch on null instead of relying on Hibernate to resolve it
3. Prefer the ENTITY_NAME_RESOLVER entry point, which returns null for non-Map values instead of throwing

Example fix

// before
Map<String,Object> entity = maybeFindEntity();
session.merge( EntityInstantiatorDynamicMap.extractEmbeddedEntityName( entity ), entity );

// after
if ( entity != null ) {
    session.merge( EntityInstantiatorDynamicMap.extractEmbeddedEntityName( entity ), entity );
}

if ( entityMap == null ) {
    // do not push null into dynamic-map operations
    return null;
}

static boolean isDynamicMapEntity(Object o) {
    return o instanceof Map<?,?> m && m.get("$type$") != null;
}

try {
    session.merge(entityName, map);
}
catch ( org.hibernate.HibernateException e ) {
    if ( "Could not determine type of dynamic map entity".equals(e.getMessage()) ) {
        throw new IllegalArgumentException("Null dynamic-map entity passed", e);
    }
    throw e;
}

When it happens

Trigger: Passing null to session operations that must resolve the entity name of a dynamic-map entity (merge/save/update with a Map argument that is null after unwrapping); internal EntityNameResolver invocations where the map reference itself is null; defensive path when a Map-typed association column resolves to null and the resolver is invoked on it.

Common situations: Dynamic-map mappings (entity-mode 'dynamic-map' / map-based entities) used with session.merge(null)/save(null) instead of the documented null-tolerant operations; helper code forwarding possibly-null maps into extractEmbeddedEntityName.

Related errors

• The specified package name cannot be null
• Name of class to load cannot be null
• Filter definition object or name is null: %s
• Fetch profile object or name is null: %s
• null is not a valid generator name

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