What causes "Unable to locate EmbeddableValuedModelPart: {}" in hibernate/hibernate-orm?

Verify the attribute at the role path is actually @Embedded (embeddable-valued), not basic or entity-valued

hibernate/hibernate-orm · error · IllegalArgumentException

Unable to locate EmbeddableValuedModelPart: {}

Error message

Unable to locate EmbeddableValuedModelPart: {}

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/internal/MappingMetamodelImpl.java:364

	@Override
	public EntityPersister getEntityDescriptor(String entityName) {
		final var entityPersister = entityPersisterMap.get( entityName );
		if ( entityPersister == null ) {
			throw new UnknownEntityTypeException( entityName );
		}
		return entityPersister;
	}

	@Override
	public EntityPersister getEntityDescriptor(NavigableRole name) {
		throw new UnsupportedOperationException();
	}

	@Override
	public EmbeddableValuedModelPart getEmbeddableValuedModelPart(NavigableRole role){
		final var embeddableMappingType = embeddableValuedModelPart.get( role );
		if ( embeddableMappingType == null ) {
			throw new IllegalArgumentException( "Unable to locate EmbeddableValuedModelPart: " + role );
		}
		return embeddableMappingType;
	}

	@Override
	public EntityPersister findEntityDescriptor(String entityName) {
		return entityPersisterMap.get( entityName );
	}

	@Override
	public EntityPersister findEntityDescriptor(Class<?> entityJavaType) {
		return findEntityDescriptor( entityJavaType.getName() );
	}

	@Override
	public boolean isEntityClass(Class<?> entityJavaType) {
		return entityPersisterMap.containsKey( entityJavaType.getName() );
	}

View on GitHub (pinned to fad1729dce)

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

Example fix

// before
EmbeddableValuedModelPart part =
    mappingMetamodel.getEmbeddableValuedModelPart(new NavigableRole("Customer", "addresss")); // typo -> IllegalArgumentException

// after
EmbeddableValuedModelPart part =
    mappingMetamodel.getEmbeddableValuedModelPart(new NavigableRole("Customer", "address")); // exact path of the @Embedded attr

Defensive patterns

Strategy: try-catch

Validate before calling

// Null-safe existence check via the null-safe sibling before the throwing accessor
EmbeddableValuedModelPart part =
    ((MappingMetamodel) sessionFactory.getMetamodel()).findCollectionDescriptor == null ? null : null;
// practical guard: verify the attribute is embeddable-valued first
EntityPersister ep = ((MappingMetamodel) sessionFactory.getMetamodel()).findEntityDescriptor("Customer");
AttributeMapping am = ep.findAttributeMapping("address");
if (am == null || !(am instanceof EmbeddedAttributeMapping)) {
  throw new IllegalArgumentException("Role Customer.address is not an embeddable-valued part");
}

Try / catch

try {
  return mappingMetamodel.getEmbeddableValuedModelPart(role);
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Unable to locate EmbeddableValuedModelPart")) {
    return null; // or degrade: enumerate valid embeddable roles and report them
  }
  throw e;
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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