{"record":{"id":"59d9c1b35ffb8bd6","repo":"hibernate/hibernate-orm","slug":"filter-alias-must-define-either-table-or-entity-at","errorCode":null,"errorMessage":"filter alias must define either table or entity attribute","messagePattern":"filter alias must define either table or entity attribute","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/model/source/internal/hbm/FilterSourceImpl.java","lineNumber":58,"sourceCode":"\t\tString conditionAttribute = filterElement.getCondition();\n\t\tString conditionContent = null;\n\n\t\tfor ( Serializable content : filterElement.getContent() ) {\n\t\t\tif ( content instanceof String string ) {\n\t\t\t\tif ( !isBlank( string ) ) {\n\t\t\t\t\tconditionContent = string.trim();\n\t\t\t\t}\n\t\t\t}\n\t\t\telse {\n\t\t\t\tfinal JaxbHbmFilterAliasMappingType aliasMapping = JaxbHbmFilterAliasMappingType.class.cast( content );\n\t\t\t\tif ( StringHelper.isNotEmpty( aliasMapping.getTable() ) ) {\n\t\t\t\t\taliasTableMap.put( aliasMapping.getAlias(), aliasMapping.getTable() );\n\t\t\t\t}\n\t\t\t\telse if ( StringHelper.isNotEmpty( aliasMapping.getEntity() ) ) {\n\t\t\t\t\taliasEntityMap.put( aliasMapping.getAlias(), aliasMapping.getTable() );\n\t\t\t\t}\n\t\t\t\telse {\n\t\t\t\t\tthrow new MappingException(\n\t\t\t\t\t\t\t\"filter alias must define either table or entity attribute\",\n\t\t\t\t\t\t\tmappingDocument.getOrigin()\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\tthis.condition = NullnessHelper.coalesce( conditionContent, conditionAttribute );\n\t\tthis.autoAliasInjection = StringHelper.isNotEmpty( explicitAutoAliasInjectionSetting )\n\t\t\t\t? Boolean.valueOf( explicitAutoAliasInjectionSetting )\n\t\t\t\t: true;\n\t}\n\n\t@Override\n\tpublic String getName() {\n\t\treturn name;\n\t}\n","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/model/source/internal/hbm/FilterSourceImpl.java#L40-L76","documentation":"Thrown while binding an hbm.xml <filter> element whose body contains an <alias> mapping sub-element (JaxbHbmFilterAliasMappingType) that defines neither table= nor entity=. Hibernate needs one of those attributes to bind each {alias} placeholder in a manually written filter condition to a concrete table or entity; with both empty it cannot resolve the condition and fails fast with a MappingException carrying the mapping origin.","triggerScenarios":"An hbm.xml <filter name='...'> element whose content is parsed as an alias mapping element instead of plain condition text, and that element lacks both table and entity attributes, e.g. <filter name='active'><alias alias='t1'/></filter>.","commonSituations":"Writing a manual filter condition with {alias} placeholders and forgetting to state which table/entity each alias maps to; attribute typos such as tableName= instead of table=; copying a <filter-def> snippet into an entity <filter> and leaving the <alias> element half-edited.","solutions":["Add either table='...' or entity='...' to the offending <alias> element inside the <filter>","Drop the <alias> element entirely and rely on auto alias injection (put the condition in the <filter-def> or as the filter element's condition text)","Validate hbm.xml files against the Hibernate hbm XSD in the build so empty alias elements fail before runtime"],"exampleFix":"// before\n<filter name='regionFilter'>\n    <alias alias='d'/>\n</filter>\n\n// after\n<filter name='regionFilter'>\n    <alias alias='d' table='distribution'/>\n</filter>","handlingStrategy":"validation","validationCode":"DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();\ndbf.setNamespaceAware(true);\nDocument doc = dbf.newDocumentBuilder().parse(new File(\"mapping.hbm.xml\"));\nNodeList aliases = doc.getElementsByTagName(\"alias\");\nfor (int i = 0; i < aliases.getLength(); i++) {\n    NamedNodeMap attrs = aliases.item(i).getAttributes();\n    boolean hasTable = attrs.getNamedItem(\"table\") != null && !attrs.getNamedItem(\"table\").getNodeValue().isBlank();\n    boolean hasEntity = attrs.getNamedItem(\"entity\") != null && !attrs.getNamedItem(\"entity\").getNodeValue().isBlank();\n    if (!hasTable && !hasEntity) {\n        throw new IllegalStateException(\"filter alias without table/entity at line \" + aliases.item(i).getUserData(\"lineNumber\"));\n    }\n}","typeGuard":null,"tryCatchPattern":"Wrap MetadataBuilder.build()/Configuration.buildSessionFactory() in try { ... } catch (MappingException e) { log e.getOrigin() (file and line) along with e.getMessage(); } - the origin points directly at the offending <alias> element. Fix the XML; do not retry.","preventionTips":["Validate every hbm.xml against the Hibernate hbm XSD in CI","Prefer auto alias injection over manual <alias> elements unless strictly needed","Keep filter conditions in <filter-def> with a default condition and reference them by name only"],"tags":["hibernate","hbm-mapping","filter-def","xml-configuration","mappingexception"],"backgroundTag":"orm-mapping-misconfiguration","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T14:17:55.899Z"}