hibernate/hibernate-orm · error · MappingException

Unable to deserialize from cached file [%s]

Error message

Unable to deserialize from cached file [%s]

What it means

In strict mode, CacheableFileXmlSource failed to Java-deserialize the cached binding (.bin) for a mapping file: readSerFile threw SerializationException. The .bin exists but cannot be read back - typically written by a different Hibernate/JDK version or corrupted on disk. Wrapped in a MappingException naming the cached file's Origin.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/CacheableFileXmlSource.java:57

			MappingBinder binder) {
		final var origin = new Origin( SourceType.FILE, xmlFile.getAbsolutePath() );
		return fromCacheableFile( xmlFile, serLocation, origin, strict, binder );
	}

	public static Binding<? extends JaxbBindableMappingDescriptor> fromCacheableFile(
			File xmlFile,
			File serLocation,
			Origin origin,
			boolean strict,
			MappingBinder binder) {
		final var serFile = resolveSerFile( xmlFile, serLocation );

		if ( strict ) {
			try {
				return new Binding<>( readSerFile( serFile ), origin );
			}
			catch ( SerializationException e ) {
				throw new MappingException(
						String.format( "Unable to deserialize from cached file [%s]", origin.getName() ) ,
						e,
						origin
				);
			}
			catch ( FileNotFoundException e ) {
				throw new MappingException(
						String.format( "Unable to locate cached file [%s]", origin.getName() ) ,
						e,
						origin
				);
			}
		}
		else {
			if ( !isSerfileObsolete( xmlFile, serFile ) ) {
				try {
					return new Binding<>( readSerFile( serFile ), origin );
				}

View on GitHub (pinned to fad1729dce)

Solutions

1. Delete the stale .bin file(s) next to the mapping (find . -name '*.bin' -delete) so the binder regenerates from the XML
2. Keep hibernate-core version consistent between cache generation and cache reads (same app, no mixed jars)
3. Regenerate caches after JDK or Hibernate upgrades rather than reusing committed/build .bin files
4. If using strict reads intentionally, pair them with a build step that refreshes the .bin files

Example fix

# before: strict read of stale cache
# -> Unable to deserialize from cached file [...]

# after: drop caches and rebuild
find . -name '*.hbm.xml.bin' -delete
mvn clean package   # or your build; caches are regenerated

// check cache freshness/consistency before strict use
File bin = serializedFileFor(xmlFile);
if (!bin.exists() || hibernateVersionOf(bin).equals(expectedVersion)) { /* regenerate */ }
else if (bin.length() == 0) { bin.delete(); }

try {
    return strictCachedBind(xmlFile);
} catch (MappingException e) {
    if (e.getCause() instanceof SerializationException) {
        binFile.delete();          // drop the stale cache
        return bindFromXml(xmlFile); // regenerate from the source XML
    }
    throw e;
}

When it happens

Trigger: Bootstrapping with cached-file binding (addCacheableFile-style APIs) in strict mode, where the .bin next to the .hbm.xml was produced by an older hibernate-core, a different JDK, or was truncated/corrupted.

Common situations: Upgrading Hibernate without cleaning generated .bin caches; switching JDK major versions; CI artifacts carrying stale .bin files; interrupted builds leaving half-written .bin files.

Related errors

• Unable to locate cached file [%s]
• The {storageEngine} storage engine is not supported
• The specified package name cannot be null
• Unknown type of binding : <bindingRoot>
• Unable to resolve <jar-file/> reference - {}

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