hibernate/hibernate-orm · error · MappingException

Unable to locate cached file [%s]

Error message

Unable to locate cached file [%s]

What it means

In strict mode, CacheableFileXmlSource attempted to read the .bin cache for a mapping and hit FileNotFoundException: the serialized cache file does not exist. Strict mode demands an already-generated cache; there is nothing to deserialize. Wrapped in a MappingException with the Origin.

Source

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

			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 );
				}
				catch ( SerializationException e ) {
					JAXB_LOGGER.unableToDeserializeCache( serFile.getName(), e );
				}
				catch ( FileNotFoundException e ) {
					JAXB_LOGGER.cachedFileNotFound( serFile.getName(), e );
				}
			}

View on GitHub (pinned to fad1729dce)

Solutions

1. Run one non-strict pass first (standard addFile/addCacheableFile non-strict behavior) so the .bin is generated, then strict reads work
2. Or generate the caches in the build (a warm-up bootstrap step) and ship them with the artifacts
3. Verify the serialization location resolves to the same path at write and read time
4. If strictness is not required, drop strict mode and let the source fall back to the XML

Example fix

// before: strict read with no generated cache
new CacheableFileXmlSource(xml, serDir, origin, true, binder).doBind(...);

// after: non-strict first to generate, strict afterwards
new CacheableFileXmlSource(xml, serDir, origin, false, binder).doBind(...); // writes .bin
new CacheableFileXmlSource(xml, serDir, origin, true, binder).doBind(...); // now succeeds

// ensure the cache exists before strict reads
File bin = serializedFileFor(xmlFile);
if (!bin.exists()) {
    nonStrictBind(xmlFile); // generates the .bin from the XML
}
return strictCachedBind(xmlFile);

try {
    return strictCachedBind(xmlFile);
} catch (MappingException e) {
    if (e.getCause() instanceof FileNotFoundException) {
        return bindFromXml(xmlFile); // no cache yet: bind from XML, optionally write cache
    }
    throw e;
}

When it happens

Trigger: Strict cached-file binding on a mapping whose .bin was never generated - first run on a clean checkout, cache directory cleaned, or wrong serLocation configured.

Common situations: Fresh clones in CI; deployments that copy only the .hbm.xml files; misconfigured cache output directory so writes and reads look in different places.

Related errors

• Unable to deserialize from 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/b70ca00f9d26f489. Report an issue: GitHub.