hibernate/hibernate-orm · error · MappingException

filter alias must define either table or entity attribute

Error message

filter alias must define either table or entity attribute

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/source/internal/hbm/FilterSourceImpl.java:58

		String conditionAttribute = filterElement.getCondition();
		String conditionContent = null;

		for ( Serializable content : filterElement.getContent() ) {
			if ( content instanceof String string ) {
				if ( !isBlank( string ) ) {
					conditionContent = string.trim();
				}
			}
			else {
				final JaxbHbmFilterAliasMappingType aliasMapping = JaxbHbmFilterAliasMappingType.class.cast( content );
				if ( StringHelper.isNotEmpty( aliasMapping.getTable() ) ) {
					aliasTableMap.put( aliasMapping.getAlias(), aliasMapping.getTable() );
				}
				else if ( StringHelper.isNotEmpty( aliasMapping.getEntity() ) ) {
					aliasEntityMap.put( aliasMapping.getAlias(), aliasMapping.getTable() );
				}
				else {
					throw new MappingException(
							"filter alias must define either table or entity attribute",
							mappingDocument.getOrigin()
					);
				}
			}
		}

		this.condition = NullnessHelper.coalesce( conditionContent, conditionAttribute );
		this.autoAliasInjection = StringHelper.isNotEmpty( explicitAutoAliasInjectionSetting )
				? Boolean.valueOf( explicitAutoAliasInjectionSetting )
				: true;
	}

	@Override
	public String getName() {
		return name;
	}

View on GitHub (pinned to fad1729dce)

Solutions

1. Add either table='...' or entity='...' to the offending <alias> element inside the <filter>
2. 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)
3. Validate hbm.xml files against the Hibernate hbm XSD in the build so empty alias elements fail before runtime

Example fix

// before
<filter name='regionFilter'>
    <alias alias='d'/>
</filter>

// after
<filter name='regionFilter'>
    <alias alias='d' table='distribution'/>
</filter>

DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
dbf.setNamespaceAware(true);
Document doc = dbf.newDocumentBuilder().parse(new File("mapping.hbm.xml"));
NodeList aliases = doc.getElementsByTagName("alias");
for (int i = 0; i < aliases.getLength(); i++) {
    NamedNodeMap attrs = aliases.item(i).getAttributes();
    boolean hasTable = attrs.getNamedItem("table") != null && !attrs.getNamedItem("table").getNodeValue().isBlank();
    boolean hasEntity = attrs.getNamedItem("entity") != null && !attrs.getNamedItem("entity").getNodeValue().isBlank();
    if (!hasTable && !hasEntity) {
        throw new IllegalStateException("filter alias without table/entity at line " + aliases.item(i).getUserData("lineNumber"));
    }
}

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.

When it happens

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

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

Related errors

• must specify an identifier type: %s
• Attribute mapping must define a name attribute: containingCl
• No filter condition found for filter [%s] associated with ma
• Attribute [%s] referenced columns from multiple tables: %s,
• many-to-one attribute [%s] specified delete-orphan but is no

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