{"record":{"id":"d765367a8b63c400","repo":"hibernate/hibernate-orm","slug":"entity-entityname-is-not-a-dynamic-entity","errorCode":null,"errorMessage":"Entity '{entityName}' is not a dynamic entity","messagePattern":"Entity '(.+?)' is not a dynamic entity","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/internal/SessionFactoryImpl.java","lineNumber":988,"sourceCode":"\n\t@Override\n\t@Nonnull\n\tpublic MappingMetamodel getMetamodel() {\n\t\tvalidateNotClosed();\n\t\treturn runtimeMetamodels.getMappingMetamodel();\n\t}\n\n\t@Override\n\tpublic boolean isOpen() {\n\t\treturn status != Status.CLOSED;\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic RootGraphImplementor<Map<String, ?>> createGraphForDynamicEntity(@Nonnull String entityName) {\n\t\tfinal var entity = getJpaMetamodel().entity( entityName );\n\t\tif ( entity.getRepresentationMode() != RepresentationMode.MAP ) {\n\t\t\tthrow new IllegalArgumentException( \"Entity '\" + entityName + \"' is not a dynamic entity\" );\n\t\t}\n\t\t@SuppressWarnings(\"unchecked\") //Safe, because we just checked\n\t\tfinal var dynamicEntity = (EntityDomainType<Map<String, ?>>) entity;\n\t\treturn new RootGraphImpl<>( null, dynamicEntity );\n\t}\n\n\t@Override\n\t@Nullable\n\tpublic RootGraphImplementor<?> findEntityGraphByName(@Nonnull String name) {\n\t\treturn getJpaMetamodel().findEntityGraphByName( name );\n\t}\n\n\t@Override\n\t@Nullable\n\tpublic String bestGuessEntityName(@Nonnull Object object) {\n\t\tfinal var initializer = extractLazyInitializer( object );\n\t\tif ( initializer != null ) {\n\t\t\t// it is possible for this method to be called during flush processing,","sourceCodeStart":970,"sourceCodeEnd":1006,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/internal/SessionFactoryImpl.java#L970-L1006","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nRootGraph<Map<String, ?>> graph =\n        sessionFactory.createGraphForDynamicEntity(\"Order\"); // Order is a POJO @Entity\n\n// after\n@Nullable RootGraphImplementor<Order> orderGraph =\n        sessionFactory.createGraph(Order.class);","handlingStrategy":"validation","validationCode":"// JPA metamodel does not expose representation mode; guard by trying the typed API first\nEntityDomainType<?> type = sessionFactory.getJpaMetamodel()\n        .getEntities().stream()\n        .filter(e -> e.getName().equals(entityName))\n        .findFirst().orElseThrow();\n// If you own the mapping: only call createGraphForDynamicEntity for Map-based mappings","typeGuard":null,"tryCatchPattern":"try {\n    return sessionFactory.createGraphForDynamicEntity(name);\n} catch (IllegalArgumentException e) {\n    // Not a Map-representation entity: fall back to the typed graph API\n    return sessionFactory.createGraph(entityClass); // or createGraph(name)\n}","preventionTips":["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"],"tags":["hibernate","entity-graph","dynamic-entity","metamodel","representation-mode"],"backgroundTag":"entity-type-mismatch","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}