{"record":{"id":"b70ca00f9d26f489","repo":"hibernate/hibernate-orm","slug":"unable-to-locate-cached-file-s","errorCode":null,"errorMessage":"Unable to locate cached file [%s]","messagePattern":"Unable to locate cached file \\[(.+?)\\]","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/CacheableFileXmlSource.java","lineNumber":64,"sourceCode":"\t\t\tFile serLocation,\n\t\t\tOrigin origin,\n\t\t\tboolean strict,\n\t\t\tMappingBinder binder) {\n\t\tfinal var serFile = resolveSerFile( xmlFile, serLocation );\n\n\t\tif ( strict ) {\n\t\t\ttry {\n\t\t\t\treturn new Binding<>( readSerFile( serFile ), origin );\n\t\t\t}\n\t\t\tcatch ( SerializationException e ) {\n\t\t\t\tthrow new MappingException(\n\t\t\t\t\t\tString.format( \"Unable to deserialize from cached file [%s]\", origin.getName() ) ,\n\t\t\t\t\t\te,\n\t\t\t\t\t\torigin\n\t\t\t\t);\n\t\t\t}\n\t\t\tcatch ( FileNotFoundException e ) {\n\t\t\t\tthrow new MappingException(\n\t\t\t\t\t\tString.format( \"Unable to locate cached file [%s]\", origin.getName() ) ,\n\t\t\t\t\t\te,\n\t\t\t\t\t\torigin\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t\telse {\n\t\t\tif ( !isSerfileObsolete( xmlFile, serFile ) ) {\n\t\t\t\ttry {\n\t\t\t\t\treturn new Binding<>( readSerFile( serFile ), origin );\n\t\t\t\t}\n\t\t\t\tcatch ( SerializationException e ) {\n\t\t\t\t\tJAXB_LOGGER.unableToDeserializeCache( serFile.getName(), e );\n\t\t\t\t}\n\t\t\t\tcatch ( FileNotFoundException e ) {\n\t\t\t\t\tJAXB_LOGGER.cachedFileNotFound( serFile.getName(), e );\n\t\t\t\t}\n\t\t\t}","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/CacheableFileXmlSource.java#L46-L82","documentation":"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.","triggerScenarios":"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.","commonSituations":"Fresh clones in CI; deployments that copy only the .hbm.xml files; misconfigured cache output directory so writes and reads look in different places.","solutions":["Run one non-strict pass first (standard addFile/addCacheableFile non-strict behavior) so the .bin is generated, then strict reads work","Or generate the caches in the build (a warm-up bootstrap step) and ship them with the artifacts","Verify the serialization location resolves to the same path at write and read time","If strictness is not required, drop strict mode and let the source fall back to the XML"],"exampleFix":"// before: strict read with no generated cache\nnew CacheableFileXmlSource(xml, serDir, origin, true, binder).doBind(...);\n\n// after: non-strict first to generate, strict afterwards\nnew CacheableFileXmlSource(xml, serDir, origin, false, binder).doBind(...); // writes .bin\nnew CacheableFileXmlSource(xml, serDir, origin, true, binder).doBind(...); // now succeeds","handlingStrategy":"fallback","validationCode":"// ensure the cache exists before strict reads\nFile bin = serializedFileFor(xmlFile);\nif (!bin.exists()) {\n    nonStrictBind(xmlFile); // generates the .bin from the XML\n}\nreturn strictCachedBind(xmlFile);","typeGuard":null,"tryCatchPattern":"try {\n    return strictCachedBind(xmlFile);\n} catch (MappingException e) {\n    if (e.getCause() instanceof FileNotFoundException) {\n        return bindFromXml(xmlFile); // no cache yet: bind from XML, optionally write cache\n    }\n    throw e;\n}","preventionTips":["Run one warm-up bootstrap after deployment to populate caches","Keep the serialization location stable between write and read","Do not use strict mode on clean checkouts without a cache-generation step"],"tags":["hibernate","mapping-cache","bootstrap","missing-file"],"backgroundTag":"stale-metadata-cache","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}