hibernate/hibernate-orm · error · MappingException

Encountered unexpected content type [%s] for named native qu

Error message

Encountered unexpected content type [%s] for named native query [%s] : [%s]

What it means

NamedQueryBinder walks the JAXB content list of a <sql-query> element and dispatches on type: return-scalar, return, return-join, load-collection, or plain text. Any other content object falls into the final branch and aborts bootstrap, so the message always names the Java class of the offending node. In practice this means a child element sits inside <sql-query> that Hibernate's hbm schema does not accept there.

Source

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

			queryBuilder.addParameterTypeHint( paramTypeBinding.getName(), paramTypeBinding.getType() );
		}
		else if ( content instanceof JaxbHbmSynchronizeType synchronizedSpace ) {
			queryBuilder.addSynchronizedQuerySpace( synchronizedSpace.getTable() );
		}
		else if ( content instanceof JaxbHbmNativeQueryScalarReturnType scalarReturnType ) {
			implicitResultSetMappingBuilder.addReturn( scalarReturnType );
		}
		else if ( content instanceof JaxbHbmNativeQueryReturnType returnType ) {
			implicitResultSetMappingBuilder.addReturn( returnType );
		}
		else if ( content instanceof JaxbHbmNativeQueryJoinReturnType jaxbHbmNativeQueryJoinReturnType ) {
			implicitResultSetMappingBuilder.addReturn( jaxbHbmNativeQueryJoinReturnType );
		}
		else if ( content instanceof JaxbHbmNativeQueryCollectionLoadReturnType collectionLoadReturnType ) {
			implicitResultSetMappingBuilder.addReturn( collectionLoadReturnType );
		}
		else {
			throw new MappingException(
					"Encountered unexpected content type [%s] for named native query [%s] : [%s]"
							.formatted( content.getClass().getName(), namedQueryBinding.getName(), content ),
					context.getOrigin()
			);
		}

		return false;
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

Inspect the direct children of the <sql-query> named in the message; only <return/>, <return-scalar/>, <return-join/> and <load-collection/> are allowed there, with the SQL itself as element text
Move or remove the offending element (e.g. a named <resultset> belongs at the top level of the mapping, not inside the query)
Validate the whole document against the hbm XSD for your Hibernate version (e.g. xmllint --schema) to surface the structural error with line numbers

Example fix

// before
<sql-query name='findPersons'>
    <resultset name='unused'/>
    <return-scalar column='id'/>
    select id, name from Person
</sql-query>

// after
<sql-query name='findPersons'>
    <return-scalar column='id'/>
    select id, name from Person
</sql-query>

Defensive patterns

Strategy: validation

Validate before calling

// Validate hbm.xml against the hbm XSD shipped with your Hibernate version before bootstrap
var factory = javax.xml.parsers.DocumentBuilderFactory.newInstance();
factory.setNamespaceAware(true);
factory.setSchema(javax.xml.validation.SchemaFactory
        .newInstance(javax.xml.XMLConstants.W3C_XML_SCHEMA_NS_URI)
        .newSchema(xsdFile));
factory.newDocumentBuilder().parse(hbmFile); // misplaced elements fail here, with line numbers

Try / catch

catch (org.hibernate.boot.MappingException e) during Metadata building: the message contains the unexpected content class name and the query name - use the class name to identify which element was misplaced, then fix the document; do not swallow, bootstrap cannot proceed without a valid mapping

Prevention

Keep hbm files XSD-validated in CI (xmllint --schema) so misplaced elements never reach the binder
Generate mappings with schema-aware tooling rather than string templates
After a Hibernate upgrade, re-validate every hbm.xml against the new XSD before deploying

When it happens

Trigger: A child element inside <sql-query> that is not <return/>, <return-scalar/>, <return-join/> or <load-collection/> - for example a stray <resultset>, a misspelled element name, or an element from another schema version or namespace. The document reached the binder only because it was not validated against the XSD beforehand.

Common situations: Hand-edited or tool-merged hbm.xml with an element nested under the wrong parent; upgrades where an older Hibernate mapping uses syntax the current hbm schema no longer accepts in that position; mappings generated by string concatenation.

Related errors

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