{"record":{"id":"13173e8728fe9f6a","repo":"hibernate/hibernate-orm","slug":"mapping-s-not-found-s-13173e","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/UrlXmlSource.java","lineNumber":42,"sourceCode":" * @see MappingBinder\n *\n * @author Steve Ebersole\n */\npublic class UrlXmlSource {\n\t/**\n\t * Create a mapping {@linkplain Binding binding} from a classpath resource (via URL).\n\t *\n\t * @see #fromUrl(URL, Origin, MappingBinder)\n\t */\n\tpublic static Binding<? extends JaxbBindableMappingDescriptor> fromResource(\n\t\t\tString resourceName,\n\t\t\tClassLoaderService classLoaderService,\n\t\t\tMappingBinder mappingBinder) {\n\t\tJAXB_LOGGER.tracef( \"Reading mappings from resource: %s\", resourceName );\n\t\tfinal var origin = new Origin( SourceType.RESOURCE, resourceName );\n\t\tfinal var url = classLoaderService.locateResource( resourceName );\n\t\tif ( url == null ) {\n\t\t\tthrow new MappingNotFoundException( origin );\n\t\t}\n\t\treturn fromUrl( url, origin, mappingBinder );\n\t}\n\n\t/**\n\t * Create a mapping {@linkplain Binding binding} from a URL\n\t *\n\t * @see #fromUrl(URL, Origin, MappingBinder)\n\t */\n\tpublic static Binding<? extends JaxbBindableMappingDescriptor> fromUrl(\n\t\t\tURL url,\n\t\t\tMappingBinder mappingBinder) {\n\t\treturn fromUrl( url, new Origin( SourceType.URL, url.toExternalForm() ), mappingBinder );\n\t}\n\n\t/**\n\t * Create a mapping {@linkplain Binding binding} from a URL\n\t *","sourceCodeStart":24,"sourceCodeEnd":60,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/UrlXmlSource.java#L24-L60","documentation":"UrlXmlSource.fromResource asks ClassLoaderService.locateResource for the mapping resource name; when it returns null, Hibernate throws MappingNotFoundException with 'Mapping (RESOURCE) not found : <name>'. The exception's Origin records exactly the resource path Hibernate tried to load.","triggerScenarios":"Configuration.addResource(\"mappings/Item.hbm.xml\"), persistence.xml <mapping-file>META-INF/orm.xml</mapping-file>, or programmatic MetadataBuilder resource adds where the path is not resolvable by the current classloaders: wrong case, wrong directory, leading slash, file not packaged, or classloader isolation hiding it.","commonSituations":"Case-sensitive path typo on Linux CI that worked on Windows/macOS; mapping file under src/main/resources excluded by build filters; resource inside a dependency jar not visible to the app-server's classloader hierarchy; path written with a leading '/' in one API and without in another.","solutions":["Check the path from the same process: Thread.currentThread().getContextClassLoader().getResource(\"<name>\") — if it returns null, fix the path or packaging","Use a path relative to the classpath root (no leading slash) and match directory case exactly","Inspect the packaged artifact (jar tf target/app.jar) to confirm the file was actually included","For app servers, ensure the module containing the mapping is visible to the module bootstrapping Hibernate"],"exampleFix":"// before\nconfiguration.addResource(\"Mappings/Item.hbm.xml\"); // actual file: mappings/item.hbm.xml\n\n// after\nconfiguration.addResource(\"mappings/item.hbm.xml\");","handlingStrategy":"validation","validationCode":"String name = \"mappings/item.hbm.xml\";\nif (Thread.currentThread().getContextClassLoader().getResource(name) == null\n        && MappingClass.class.getClassLoader().getResource(name) == null) {\n    throw new IllegalStateException(\"mapping resource not on classpath: \" + name);\n}\nconfiguration.addResource(name);","typeGuard":null,"tryCatchPattern":"catch (MappingNotFoundException e) {\n    // e.getOrigin().getName() is the exact path Hibernate tried\n    throw new IllegalStateException(\"Mapping not found on classpath: \" + e.getOrigin(), e);\n}","preventionTips":["Always derive mapping paths from constants shared with the resource layout","Add a packaging assertion (jar tf check) in CI that mapping files exist at expected paths","Prefer classpath-root-relative paths without leading slashes"],"tags":["classpath","mapping-file","resource","bootstrap"],"backgroundTag":"classpath-resource-not-found","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}