hibernate/hibernate-orm · error · InvalidMappingException

Could not parse mapping document: %s (%s)

Error message

Could not parse mapping document: %s (%s)

What it means

InputStreamXmlSource.fromStream wraps any exception thrown while the MappingBinder binds the stream into InvalidMappingException ('Could not parse mapping document: %s (%s') with the Origin. It is the umbrella error for reading a mapping document from a stream: StAX reader failures, root-element problems, JAXB unmarshalling and schema-validation errors all land here.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/InputStreamXmlSource.java:60

	/**
	 * Utility form to create a {@linkplain Binding binding} from an input source.
	 *
	 * @param stream The stream from which to read the mappings
	 * @param origin Description of the source from which the stream came
	 * @param autoClose Whether to {@linkplain InputStream#close() close} the stream after we have processed it
	 * @param binder The JAXB binder to use
	 */
	public static Binding<? extends JaxbBindableMappingDescriptor> fromStream(
			InputStream stream,
			Origin origin,
			boolean autoClose,
			MappingBinder binder) {
		try {
			return binder.bind( stream, origin );
		}
		catch ( Exception e ) {
			throw new InvalidMappingException( origin, e );
		}
		finally {
			if ( autoClose ) {
				try {
					stream.close();
				}
				catch ( IOException ioe ) {
					JAXB_LOGGER.unableToCloseInputStream( ioe );
				}
			}
		}
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

1. Unwrap getCause() - it is the specific StAX/JAXB/root-element failure with position detail
2. Open the document named by the Origin and validate it (well-formedness first, then against the Hibernate XSD)
3. Fix the reported construct, or align the document's namespace/version with the Hibernate version in use
4. If the stream itself is the problem (already consumed/closed), pass a fresh stream

Example fix

// before
try {
    sources.addResource(name); // throws InvalidMappingException
} catch (InvalidMappingException e) { /* only message kept, cause lost */ }

// after: keep the cause for diagnosis
try {
    sources.addResource(name);
} catch (InvalidMappingException e) {
    throw new IllegalStateException("Bad mapping " + name, e.getCause());
}

// pre-flight: parse the document exactly as the binder will
try (InputStream in = openMappingStream(name)) {
    javax.xml.parsers.DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(in);
} catch (Exception e) {
    throw new IllegalArgumentException("Mapping '" + name + "' fails pre-parse: " + e.getMessage(), e);
}

try {
    metadataSources.addResource(name);
} catch (InvalidMappingException e) {
    // unwrap: the cause is the specific StAX/JAXB failure with line info
    log.error("Invalid mapping {} : {}", name, e.getCause().getMessage(), e.getCause());
    throw e;
}

When it happens

Trigger: Adding a mapping via stream (addResource from classpath, URL, etc.) where the document fails at any binding stage: not well-formed, wrong root/namespace, XSD violations, or unmarshal type errors.

Common situations: Classpath mappings edited by hand; documents copied from other Hibernate versions; encoding damage in transit; any of the lower-level causes (StAX/JAXB) reached via stream-based APIs.

Related errors

• Unable to create StAX reader
• Error accessing StAX stream
• Unknown type of binding : <bindingRoot>
• Could not locate root element
• Unable to perform unmarshalling at line number {} and column

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