{"record":{"id":"9ddca08f566a3f4a","repo":"hibernate/hibernate-orm","slug":"owner-alias-owneralias-is-unknown-for-alias","errorCode":null,"errorMessage":"Owner alias [{ownerAlias}] is unknown for alias [{alias}]","messagePattern":"Owner alias \\[(.+?)\\] is unknown for alias \\[(.+?)\\]","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/query/sql/internal/ResultSetMappingProcessor.java","lineNumber":544,"sourceCode":"\t\tfinal String keyPrefix = \"element.\";\n\t\tfor ( var element : propertyResults.entrySet() ) {\n\t\t\tfinal String path = element.getKey();\n\t\t\tif ( path.startsWith( keyPrefix ) ) {\n\t\t\t\tresult.put( path.substring( keyPrefix.length() ),\n\t\t\t\t\t\telement.getValue() );\n\t\t\t}\n\t\t}\n\t\treturn result;\n\t}\n\n\tprivate void processFetchReturn(NativeQuery.FetchReturn fetchReturn) {\n\t\tfinal String alias = fetchReturn.getTableAlias();\n\t\tif ( !alias2Persister.containsKey( alias ) && !alias2CollectionPersister.containsKey( alias ) ) {\n\t\t\tfinal String ownerAlias = fetchReturn.getOwnerAlias();\n\n\t\t\t// Make sure the owner alias is known...\n\t\t\tif ( !alias2Return.containsKey( ownerAlias ) ) {\n\t\t\t\tthrow new HibernateException( \"Owner alias [\" + ownerAlias + \"] is unknown for alias [\" + alias + \"]\" );\n\t\t\t}\n\n\t\t\t// If this return's alias has not been processed yet, do so before further processing of this return\n\t\t\tif ( !alias2Persister.containsKey( ownerAlias ) ) {\n\t\t\t\tprocessReturn( alias2Return.get( ownerAlias ) );\n\t\t\t}\n\n\t\t\tfinal var ownerPersister = alias2Persister.get( ownerAlias );\n\t\t\tfinal String fetchableName = fetchReturn.getFetchable().getFetchableName();\n\t\t\tfinal var returnType = ownerPersister.getPropertyType( fetchableName );\n\t\t\tif ( returnType instanceof CollectionType ) {\n\t\t\t\taddCollection(\n\t\t\t\t\t\townerPersister.getEntityName() + '.' + fetchableName,\n\t\t\t\t\t\talias,\n\t\t\t\t\t\temptyMap() //fetchReturn.getPropertyResultsMap()\n\t\t\t\t);\n\t//\t\t\tcollectionOwnerAliases.add( ownerAlias );\n\t\t\t}","sourceCodeStart":526,"sourceCodeEnd":562,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/sql/internal/ResultSetMappingProcessor.java#L526-L562","documentation":"While processing a legacy native-query return mapping, ResultSetMappingProcessor.processFetchReturn resolves each fetch return's owner alias. If the owner alias was never declared among the query's returns (alias2Return does not contain it), Hibernate throws HibernateException — it has no entity/collection persister to fetch from for that alias.","triggerScenarios":"Programmatic legacy mapping: query.addFetch(\"k\", \"mother\", \"kittens\") where no addEntity(\"mother\", ...) / addRoot / addJoin declared the alias 'mother' earlier. Also hbm.xml <return-join>/<return-fetch> style mappings whose owner alias does not match any declared return alias (typo, case mismatch, or missing <return> entry).","commonSituations":"Migrating old Hibernate-native query mappings (addEntity/addJoin/addFetch) to Hibernate 6 where alias handling is stricter; typos or renamed aliases in hbm.xml mapping documents; returns added in the wrong order so the fetch is processed before its owner is registered.","solutions":["Declare the owner return before the fetch: addEntity/addRoot/addJoin with the exact alias used as ownerAlias.","Check the alias spelling and case — owner alias must exactly equal the declared table alias.","Prefer addJoin(\"alias\", \"ownerAlias.property\") which implies the owner, or migrate to @SqlResultSetMapping / resultClass-based mappings."],"exampleFix":"// before\nNativeQuery<?> q = session.createNativeQuery(\"select {m.*}, {k.*} from cat m join kitten k on k.mother_id = m.id\");\nq.addEntity(\"m\", Cat.class);\nq.addFetch(\"k\", \"mother\", \"kittens\"); // owner alias \"mother\" never declared\n\n// after\nq.addEntity(\"m\", Cat.class);\nq.addJoin(\"k\", \"m.kittens\");","handlingStrategy":"validation","validationCode":"java.util.Set<String> declaredAliases = new java.util.HashSet<>();\n// populate as you add returns: addEntity/addRoot/addJoin each register an alias\ndeclaredAliases.add(\"m\");\n\nString ownerAlias = \"m\"; // alias you intend to pass to addFetch\nif (!declaredAliases.contains(ownerAlias)) throw new IllegalArgumentException(\"Owner alias '\" + ownerAlias + \"' not declared — add it with addEntity/addJoin before addFetch\");\nquery.addFetch(\"k\", ownerAlias, \"kittens\");","typeGuard":null,"tryCatchPattern":"try { ((org.hibernate.query.sql.spi.NativeQueryImplementor<?>) query).list(); } catch (org.hibernate.HibernateException e) { /* if 'Owner alias ... is unknown', verify declared aliases and mapping order */ throw e; }","preventionTips":["Wrap native-query mapping construction in a builder that tracks declared aliases and validates addFetch/addJoin owner references.","Prefer addJoin(\"alias\", \"ownerAlias.property\") over manual addFetch.","Keep a unit test per legacy native-query mapping so alias typos fail at build time."],"tags":["hibernate","native-query","legacy-mapping","result-mapping","alias"],"backgroundTag":"unknown-alias-in-native-query-mapping","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}