{"record":{"id":"0dbfe2ce92fe48ff","repo":"hibernate/hibernate-orm","slug":"mapping-s-not-found-s-0dbfe2","errorCode":null,"errorMessage":"Mapping (%s) not found : %s","messagePattern":"Mapping \\((.+?)\\) not found : (.+?)","errorType":"exception","errorClass":"MappingNotFoundException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/JarFileEntryXmlSource.java","lineNumber":57,"sourceCode":"\t */\n\tpublic static void fromJar(\n\t\t\tFile jar,\n\t\t\tMappingBinder mappingBinder,\n\t\t\tConsumer<Binding<? extends JaxbBindableMappingDescriptor>> consumer) {\n\t\tJAXB_LOGGER.tracef( \"Seeking mapping documents in jar file: %s\", jar.getName() );\n\t\tfinal var origin = new Origin( SourceType.JAR, jar.getAbsolutePath() );\n\t\ttry ( var jarFile = new JarFile( jar ) ) {\n\t\t\tfinal var entries = jarFile.entries();\n\t\t\twhile ( entries.hasMoreElements() ) {\n\t\t\t\tfinal var jarEntry = entries.nextElement();\n\t\t\t\tif ( jarEntry.getName().endsWith(\".hbm.xml\") ) {\n\t\t\t\t\tJAXB_LOGGER.tracef( \"Found 'hbm.xml' mapping in jar: %s\", jarEntry.getName() );\n\t\t\t\t\tconsumer.accept( fromJarEntry( jarFile, jarEntry, origin, mappingBinder ) );\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tcatch ( IOException e ) {\n\t\t\tthrow new MappingNotFoundException( e, origin );\n\t\t}\n\t}\n\n\t/**\n\t * Create a mapping {@linkplain Binding binding} from a JAR file entry.\n\t */\n\tpublic static Binding<? extends JaxbBindableMappingDescriptor> fromJarEntry(\n\t\t\tJarFile jarFile,\n\t\t\tZipEntry jarFileEntry,\n\t\t\tOrigin origin,\n\t\t\tMappingBinder mappingBinder) {\n\t\tfinal InputStream stream;\n\t\ttry {\n\t\t\tstream = jarFile.getInputStream( jarFileEntry );\n\t\t}\n\t\tcatch (IOException e) {\n\t\t\tthrow new MappingException(\n\t\t\t\t\tString.format(","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/JarFileEntryXmlSource.java#L39-L75","documentation":"JarFileEntryXmlSource scans a jar for *.hbm.xml entries; any IOException while opening or reading the jar is wrapped in MappingNotFoundException with a JAR-type Origin naming the jar path. The jar could not be opened or enumerated - unlike the plain file case, this often means unreadable/corrupt rather than absent.","triggerScenarios":"addJar(new File(...)) where the path is not a valid zip/jar, the file is locked by another process (Windows), or the jar was truncated during download/copy.","commonSituations":"Corrupt artifacts pulled from broken mirrors; partially copied jars in Docker layers; fat/uber-jar repackaging that damaged entries; permissions on the jar file.","solutions":["Verify the archive opens: jar tf myapp.jar | head (or unzip -l) - a CRC/zip error confirms corruption","Re-download or rebuild the jar from a trusted source and redeploy","Check file permissions and, on Windows, that nothing holds an exclusive lock","If you only need specific mappings inside the jar, extract them and register them as files/resources instead"],"exampleFix":"# before: corrupt jar fails during scan\nsources.addJar(new File(\"libs/legacy-mappings.jar\"));\n\n# after: verify, then re-register a good copy\n$ jar tf libs/legacy-mappings.jar   # exposes zip error\n$ mvn deploy:deploy-file ...        # or re-copy from source\nsources.addJar(new File(\"libs/legacy-mappings.jar\"));","handlingStrategy":"validation","validationCode":"// verify the jar opens cleanly before registering it\nFile jar = new File(path);\nif (!jar.isFile()) throw new IllegalArgumentException(\"Not a jar file: \" + jar.getAbsolutePath());\ntry (var jf = new java.util.jar.JarFile(jar)) {\n    if (!jf.entries().hasMoreElements()) throw new IllegalArgumentException(\"Empty jar: \" + path);\n} catch (IOException e) {\n    throw new IllegalArgumentException(\"Unreadable/corrupt jar: \" + path, e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    metadataSources.addJar(new File(path));\n} catch (MappingNotFoundException e) {\n    // Origin names the jar; verify with 'jar tf' - corrupt archives must be re-fetched\n    log.error(\"Cannot read mapping jar: {}\", e.getMessage(), e);\n    throw e;\n}","preventionTips":["Verify jar integrity (jar tf / checksums) during deployment","Extract-and-register individual mapping files when only a few are needed","Avoid registering jars whose lifecycle is managed by another process"],"tags":["hibernate","mapping-file","jar","bootstrap","corrupt-archive"],"backgroundTag":"mapping-file-not-found","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}