hibernate/hibernate-orm · error · MappingException

Unable to perform unmarshalling at line number {} and column

Error message

Unable to perform unmarshalling at line number {} and column {}. Message: {}

What it means

JAXB unmarshalling of the mapping document failed; the message embeds the line and column captured by the ValidationEventHandler plus that handler's message. Schema validation is attached to the unmarshaller when enabled, so both raw unmarshal errors and XSD validation failures surface here, wrapped in a MappingException with the Origin.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/AbstractBinder.java:165

	protected <X extends T> X jaxb(XMLEventReader reader, Schema xsd, JAXBContext jaxbContext, Origin origin) {
		final ContextProvidingValidationEventHandler handler = new ContextProvidingValidationEventHandler();

		try {
			final Unmarshaller unmarshaller = jaxbContext.createUnmarshaller();
			if ( isValidationEnabled() ) {
				unmarshaller.setSchema( xsd );
			}
			else {
				unmarshaller.setSchema( null );
			}
			unmarshaller.setEventHandler( handler );

			//noinspection unchecked
			return (X) unmarshaller.unmarshal( reader );
		}
		catch ( JAXBException e ) {
			throw new MappingException(
					"Unable to perform unmarshalling at line number " + handler.getLineNumber()
							+ " and column " + handler.getColumnNumber()
							+ ". Message: " + handler.getMessage(),
					e,
					origin
			);
		}
	}


}

View on GitHub (pinned to fad1729dce)

Solutions

Go to the reported line:column in the file named by the Origin - the handler message names the offending element/value
Fix the element/attribute per the schema for your Hibernate version (check the bundled XSD or docs)
Verify the root namespace matches the version in use (e.g. current hibernate-mapping/cfg/mapping namespaces)
Run a local schema validation pass to catch remaining errors before boot
If deviating intentionally, validation can be disabled on the binder - but the document must still unmarshal

Example fix

<!-- before: unknown attribute + bad numeric -->
<set name="tags" lAZY="true" batch-size="ten">...</set>

<!-- after -->
<set name="tags" lazy="true" batch-size="10">...</set>

Defensive patterns

Strategy: validation

Validate before calling

// schema-validate before boot to collect ALL problems with positions
var factory = javax.xml.validation.SchemaFactory.newInstance(javax.xml.XMLConstants.W3C_XML_SCHEMA_NS_URI);
var schema = factory.newSchema(getClass().getResource("/org/hibernate/xsd/hibernate-mapping-4.0.xsd"));
var validator = schema.newValidator();
final var problems = new java.util.ArrayList<String>();
validator.setErrorHandler(new org.xml.sax.helpers.DefaultHandler() {
    public void error(org.xml.sax.SAXParseException e) { problems.add(e.getLine() + ":" + e.getColumn() + " " + e.getMessage()); }
});
validator.validate(new javax.xml.transform.stream.StreamSource(mappingFile));

Try / catch

try {
    binder.bind(stream, origin);
} catch (MappingException e) {
    // message carries line/column from the ValidationEventHandler
    log.error("mapping invalid at {}", e.getMessage(), e.getCause());
    throw e;
}

Prevention

Validate mapping XML against the Hibernate XSD in CI
Use editor XML schema support while editing mappings
Match document namespaces to the Hibernate version in use

When it happens

Trigger: Binding an hbm.xml/cfg.xml/mapping.xml that violates its XSD: unknown elements or attributes, wrong namespace, text where an integer/date is expected, required attribute missing. Also plain JAXB errors such as unexpected root element names.

Common situations: Hand-edited mapping files with typos; files written for a different Hibernate version's schema; copy-pasted snippets from older docs using the old DTD or a stale namespace; attribute values like 'truee' or non-numeric in numeric fields.

Related errors

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