{"record":{"id":"289bd8b928e4507c","repo":"hibernate/hibernate-orm","slug":"could-not-determine-type-of-dynamic-map-entity","errorCode":null,"errorMessage":"Could not determine type of dynamic map entity","messagePattern":"Could not determine type of dynamic map entity","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/metamodel/internal/EntityInstantiatorDynamicMap.java","lineNumber":55,"sourceCode":"\tpublic Object instantiate() {\n\t\treturn generateDataMap();\n\t}\n\n\t@Override\n\tprotected boolean isSameRole(String type) {\n\t\treturn super.isSameRole( type ) || isPartOfHierarchy( type );\n\t}\n\n\tprivate boolean isPartOfHierarchy(String type) {\n\t\treturn entityRoleNames.contains( type );\n\t}\n\n\tpublic static final EntityNameResolver ENTITY_NAME_RESOLVER =\n\t\t\tentity -> entity instanceof Map<?, ?> map ? extractEmbeddedEntityName( map ) : null;\n\n\tpublic static String extractEmbeddedEntityName(Map<?,?> entity) {\n\t\tif ( entity == null ) {\n\t\t\tthrow new HibernateException( \"Could not determine type of dynamic map entity\" );\n\t\t}\n\t\telse {\n\t\t\tfinal String entityName = (String) entity.get( TYPE_KEY );\n\t\t\tif ( entityName == null ) {\n\t\t\t\tthrow new HibernateException( \"Could not determine type of dynamic map entity\" );\n\t\t\t}\n\t\t\treturn entityName;\n\t\t}\n\t}\n}\n","sourceCodeStart":37,"sourceCodeEnd":66,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/metamodel/internal/EntityInstantiatorDynamicMap.java#L37-L66","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Null-check map arguments before calling session operations like merge/save/update on dynamic-map entities","If the value may legitimately be absent, branch on null instead of relying on Hibernate to resolve it","Prefer the ENTITY_NAME_RESOLVER entry point, which returns null for non-Map values instead of throwing"],"exampleFix":"// before\nMap<String,Object> entity = maybeFindEntity();\nsession.merge( EntityInstantiatorDynamicMap.extractEmbeddedEntityName( entity ), entity );\n\n// after\nif ( entity != null ) {\n    session.merge( EntityInstantiatorDynamicMap.extractEmbeddedEntityName( entity ), entity );\n}","handlingStrategy":"type-guard","validationCode":"if ( entityMap == null ) {\n    // do not push null into dynamic-map operations\n    return null;\n}","typeGuard":"static boolean isDynamicMapEntity(Object o) {\n    return o instanceof Map<?,?> m && m.get(\"$type$\") != null;\n}","tryCatchPattern":"try {\n    session.merge(entityName, map);\n}\ncatch ( org.hibernate.HibernateException e ) {\n    if ( \"Could not determine type of dynamic map entity\".equals(e.getMessage()) ) {\n        throw new IllegalArgumentException(\"Null dynamic-map entity passed\", e);\n    }\n    throw e;\n}","preventionTips":["Null-check map arguments before every dynamic-map session operation","Route name resolution through EntityNameResolver semantics (returns null for non-maps) instead of raw helper calls","Plan a migration off dynamic-map entity mode - it is legacy support"],"tags":["hibernate","dynamic-map","entity-mode","null-check"],"backgroundTag":"dynamic-map-entity-type-missing","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}