hibernate/hibernate-orm · error · MappingException

Entity <return/> mapping did not specify entity name

Error message

Entity <return/> mapping did not specify entity name

What it means

When interpreting an entity <return/> from an HBM native query mapping, Hibernate resolves the entity name from the entity-name attribute, or by looking the clazz value up in the metadata collector's imports. If both routes yield null this MappingException is thrown: neither an entity-name was supplied nor is the class name a known imported entity name.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/query/HbmResultSetMappingDescriptor.java:336

		private final Supplier<Map<String, Map<String, JoinDescriptor>>> joinDescriptorsAccess;

		private final String registrationName;

		public EntityResultDescriptor(
				JaxbHbmNativeQueryReturnType hbmEntityReturn,
				Supplier<Map<String, Map<String, JoinDescriptor>>> joinDescriptorsAccess,
				String registrationName,
				MetadataBuildingContext context) {
			assert joinDescriptorsAccess != null;
			this.joinDescriptorsAccess = joinDescriptorsAccess;
			this.registrationName = registrationName;

			entityName =
					hbmEntityReturn.getEntityName() == null
							? context.getMetadataCollector().getImports().get( hbmEntityReturn.getClazz() )
							: hbmEntityReturn.getEntityName();
			if ( entityName == null ) {
				throw new MappingException(
						"Entity <return/> mapping did not specify entity name"
				);
			}

			tableAlias = hbmEntityReturn.getAlias();
			if ( tableAlias == null ) {
				throw new MappingException(
						"Entity <return/> mapping did not specify alias"
				);
			}

			BootQueryLogging.BOOT_QUERY_LOGGER.tracef(
					"Creating EntityResultDescriptor (%s : %s) for ResultSet mapping - %s",
					tableAlias,
					entityName,
					registrationName
			);

View on GitHub (pinned to fad1729dce)

Solutions

1. Set the entity-name attribute explicitly: <return alias="o" entity-name="com.acme.Order"/>.
2. Or make clazz the fully qualified class name of a mapped entity.
3. Verify the target entity is actually mapped (annotations or hbm.xml included in the same Metadata bootstrap) and that its name/auto-import resolves.
4. Fix typos in the clazz value.

Example fix

<!-- before: 'Order' is not an imported/mapped entity name -->
<return alias="o" clazz="Order"/>

<!-- after -->
<return alias="o" entity-name="com.acme.Order"/>

// after building Metadata (before SessionFactory), verify names used in <return> resolve:
Metadata metadata = sources.buildMetadata();
for ( String clazzName : returnClazzValues ) {
    String resolved = metadata.getImports().containsKey( clazzName )
            ? metadata.getImports().get( clazzName ) : null;
    if ( resolved == null && entityNameAttr == null ) {
        throw new IllegalStateException( "Unknown entity in query mapping: " + clazzName );
    }
}

catch ( MappingException e ) {
    if ( "Entity <return/> mapping did not specify entity name".equals( e.getMessage() ) ) {
        // add entity-name= or fix the clazz value in the named mapping file
    }
}

When it happens

Trigger: <return alias="o" clazz="Order"/> when no entity named 'Order' (or com.acme.Order) is mapped; typo in clazz; using the short class name of an entity mapped only under its fully-qualified name without an auto-import; entity-name-based entity referenced via clazz.

Common situations: The native query mapping is processed before/without the entity's own mapping on the classpath; auto-import disabled in the persistence unit; entities renamed during refactoring; hbm.xml files consolidated while clazz values kept old names.

Related errors

• Cannot combine other returns with a collection return (" + r
• Illegal <return-join/> property attribute: '" + fullProperty
• Entity <return/> mapping did not specify alias
• property [" + propertyPath + "] not found on entity [" + ent
• Illegal <return-join/> property attribute: '" + fullProperty

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