{"record":{"id":"fbc4fa9369efa46a","repo":"hibernate/hibernate-orm","slug":"entity-return-mapping-did-not-specify-entity-na","errorCode":null,"errorMessage":"Entity <return/> mapping did not specify entity name","messagePattern":"Entity <return/> mapping did not specify entity name","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/query/HbmResultSetMappingDescriptor.java","lineNumber":336,"sourceCode":"\t\tprivate final Supplier<Map<String, Map<String, JoinDescriptor>>> joinDescriptorsAccess;\n\n\t\tprivate final String registrationName;\n\n\t\tpublic EntityResultDescriptor(\n\t\t\t\tJaxbHbmNativeQueryReturnType hbmEntityReturn,\n\t\t\t\tSupplier<Map<String, Map<String, JoinDescriptor>>> joinDescriptorsAccess,\n\t\t\t\tString registrationName,\n\t\t\t\tMetadataBuildingContext context) {\n\t\t\tassert joinDescriptorsAccess != null;\n\t\t\tthis.joinDescriptorsAccess = joinDescriptorsAccess;\n\t\t\tthis.registrationName = registrationName;\n\n\t\t\tentityName =\n\t\t\t\t\thbmEntityReturn.getEntityName() == null\n\t\t\t\t\t\t\t? context.getMetadataCollector().getImports().get( hbmEntityReturn.getClazz() )\n\t\t\t\t\t\t\t: hbmEntityReturn.getEntityName();\n\t\t\tif ( entityName == null ) {\n\t\t\t\tthrow new MappingException(\n\t\t\t\t\t\t\"Entity <return/> mapping did not specify entity name\"\n\t\t\t\t);\n\t\t\t}\n\n\t\t\ttableAlias = hbmEntityReturn.getAlias();\n\t\t\tif ( tableAlias == null ) {\n\t\t\t\tthrow new MappingException(\n\t\t\t\t\t\t\"Entity <return/> mapping did not specify alias\"\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tBootQueryLogging.BOOT_QUERY_LOGGER.tracef(\n\t\t\t\t\t\"Creating EntityResultDescriptor (%s : %s) for ResultSet mapping - %s\",\n\t\t\t\t\ttableAlias,\n\t\t\t\t\tentityName,\n\t\t\t\t\tregistrationName\n\t\t\t);\n","sourceCodeStart":318,"sourceCodeEnd":354,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/query/HbmResultSetMappingDescriptor.java#L318-L354","documentation":"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.","triggerScenarios":"<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.","commonSituations":"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.","solutions":["Set the entity-name attribute explicitly: <return alias=\"o\" entity-name=\"com.acme.Order\"/>.","Or make clazz the fully qualified class name of a mapped entity.","Verify the target entity is actually mapped (annotations or hbm.xml included in the same Metadata bootstrap) and that its name/auto-import resolves.","Fix typos in the clazz value."],"exampleFix":"<!-- before: 'Order' is not an imported/mapped entity name -->\n<return alias=\"o\" clazz=\"Order\"/>\n\n<!-- after -->\n<return alias=\"o\" entity-name=\"com.acme.Order\"/>","handlingStrategy":"validation","validationCode":"// after building Metadata (before SessionFactory), verify names used in <return> resolve:\nMetadata metadata = sources.buildMetadata();\nfor ( String clazzName : returnClazzValues ) {\n    String resolved = metadata.getImports().containsKey( clazzName )\n            ? metadata.getImports().get( clazzName ) : null;\n    if ( resolved == null && entityNameAttr == null ) {\n        throw new IllegalStateException( \"Unknown entity in query mapping: \" + clazzName );\n    }\n}","typeGuard":null,"tryCatchPattern":"catch ( MappingException e ) {\n    if ( \"Entity <return/> mapping did not specify entity name\".equals( e.getMessage() ) ) {\n        // add entity-name= or fix the clazz value in the named mapping file\n    }\n}","preventionTips":["Prefer fully qualified entity names (or explicit entity-name attributes) in native query mappings.","Keep a single integration test that boots the full Metadata so unmapped names fail fast in CI.","When renaming entities, grep hbm.xml files for the old names."],"tags":["hibernate","hbm-xml","native-query","entity-resolution","boot"],"backgroundTag":"unresolvable-entity-name","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}