{"record":{"id":"a627e8e0db3894fb","repo":"hibernate/hibernate-orm","slug":"unable-to-locate-embeddablevaluedmodelpart","errorCode":null,"errorMessage":"Unable to locate EmbeddableValuedModelPart: {}","messagePattern":"Unable to locate EmbeddableValuedModelPart: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/internal/MappingMetamodelImpl.java","lineNumber":364,"sourceCode":"\t@Override\n\tpublic EntityPersister getEntityDescriptor(String entityName) {\n\t\tfinal var entityPersister = entityPersisterMap.get( entityName );\n\t\tif ( entityPersister == null ) {\n\t\t\tthrow new UnknownEntityTypeException( entityName );\n\t\t}\n\t\treturn entityPersister;\n\t}\n\n\t@Override\n\tpublic EntityPersister getEntityDescriptor(NavigableRole name) {\n\t\tthrow new UnsupportedOperationException();\n\t}\n\n\t@Override\n\tpublic EmbeddableValuedModelPart getEmbeddableValuedModelPart(NavigableRole role){\n\t\tfinal var embeddableMappingType = embeddableValuedModelPart.get( role );\n\t\tif ( embeddableMappingType == null ) {\n\t\t\tthrow new IllegalArgumentException( \"Unable to locate EmbeddableValuedModelPart: \" + role );\n\t\t}\n\t\treturn embeddableMappingType;\n\t}\n\n\t@Override\n\tpublic EntityPersister findEntityDescriptor(String entityName) {\n\t\treturn entityPersisterMap.get( entityName );\n\t}\n\n\t@Override\n\tpublic EntityPersister findEntityDescriptor(Class<?> entityJavaType) {\n\t\treturn findEntityDescriptor( entityJavaType.getName() );\n\t}\n\n\t@Override\n\tpublic boolean isEntityClass(Class<?> entityJavaType) {\n\t\treturn entityPersisterMap.containsKey( entityJavaType.getName() );\n\t}","sourceCodeStart":346,"sourceCodeEnd":382,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/internal/MappingMetamodelImpl.java#L346-L382","documentation":"MappingMetamodelImpl.getEmbeddableValuedModelPart(NavigableRole) resolves a role to an embeddable-valued model part from the embeddableValuedModelPart map; a miss throws IllegalArgumentException('Unable to locate EmbeddableValuedModelPart: ' + role). The role must be the exact full navigable path of an @Embedded/@Embeddable-valued attribute.","triggerScenarios":"Calling MappingMetamodel#getEmbeddableValuedModelPart with a role that is not an embeddable part: a basic- or entity-valued attribute path, a mistyped/misspelled role string, or a role whose owning entity is mapped in another persistence unit. Mostly reached through internal SPIs, custom integrations, or tooling that walks the mapping model.","commonSituations":"Custom code builds role strings by hand ('Entity.embeddedProp') and drifts from the real mapping; assuming an @Embedded target resolves here when the attribute is actually entity-valued (@ManyToOne); upgrading Hibernate where role formats changed.","solutions":["Verify the attribute at the role path is actually @Embedded (embeddable-valued), not basic or entity-valued","Build the role from the mapping itself (attributeMapping.getNavigableRole().getFullPath()) instead of concatenating strings by hand","Use a null-safe lookup first (e.g. check via role enumeration / find-style accessors on MappingMetamodel) and report the miss before calling"],"exampleFix":"// before\nEmbeddableValuedModelPart part =\n    mappingMetamodel.getEmbeddableValuedModelPart(new NavigableRole(\"Customer\", \"addresss\")); // typo -> IllegalArgumentException\n\n// after\nEmbeddableValuedModelPart part =\n    mappingMetamodel.getEmbeddableValuedModelPart(new NavigableRole(\"Customer\", \"address\")); // exact path of the @Embedded attr","handlingStrategy":"try-catch","validationCode":"// Null-safe existence check via the null-safe sibling before the throwing accessor\nEmbeddableValuedModelPart part =\n    ((MappingMetamodel) sessionFactory.getMetamodel()).findCollectionDescriptor == null ? null : null;\n// practical guard: verify the attribute is embeddable-valued first\nEntityPersister ep = ((MappingMetamodel) sessionFactory.getMetamodel()).findEntityDescriptor(\"Customer\");\nAttributeMapping am = ep.findAttributeMapping(\"address\");\nif (am == null || !(am instanceof EmbeddedAttributeMapping)) {\n  throw new IllegalArgumentException(\"Role Customer.address is not an embeddable-valued part\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  return mappingMetamodel.getEmbeddableValuedModelPart(role);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"Unable to locate EmbeddableValuedModelPart\")) {\n    return null; // or degrade: enumerate valid embeddable roles and report them\n  }\n  throw e;\n}","preventionTips":["Build NavigableRole values from the mapping model itself (attributeMapping.getNavigableRole()) instead of string concatenation","Log the requested role next to known roles on failure — this is an internal SPI, exact paths matter","Cover role-format assumptions with unit tests; they can change across Hibernate majors"],"tags":["hibernate","embeddable","mapping-model","internal-api"],"backgroundTag":"embeddable-mapping-not-found","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}