{"record":{"id":"3f31ac4f9091dd80","repo":"hibernate/hibernate-orm","slug":"unable-to-locate-schema-via-classpath","errorCode":null,"errorMessage":"Unable to locate schema [{}] via classpath","messagePattern":"Unable to locate schema \\[(.+?)\\] via classpath","errorType":"exception","errorClass":"XsdException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/xsd/LocalXsdResolver.java","lineNumber":78,"sourceCode":"\t\t\tcatch (Exception ignore) {\n\t\t\t}\n\t\t}\n\n\t\t// Last: we try name as a URL\n\t\ttry {\n\t\t\treturn new URL( resourceName );\n\t\t}\n\t\tcatch (Exception ignore) {\n\t\t}\n\n\t\treturn null;\n\t}\n\n\n\tpublic static Schema resolveLocalXsdSchema(String schemaResourceName) {\n\t\tfinal URL url = resolveLocalXsdUrl( schemaResourceName );\n\t\tif ( url == null ) {\n\t\t\tthrow new XsdException( \"Unable to locate schema [\" + schemaResourceName + \"] via classpath\", schemaResourceName );\n\t\t}\n\t\ttry {\n\t\t\tfinal var schemaStream = url.openStream();\n\t\t\ttry {\n\t\t\t\treturn SchemaFactory.newInstance( W3C_XML_SCHEMA_NS_URI )\n\t\t\t\t\t\t.newSchema( new StreamSource( url.openStream() ) );\n\t\t\t}\n\t\t\tcatch ( SAXException | IOException e ) {\n\t\t\t\tthrow new XsdException( \"Unable to load schema [\" + schemaResourceName + \"]\", e, schemaResourceName );\n\t\t\t}\n\t\t\tfinally {\n\t\t\t\ttry {\n\t\t\t\t\tschemaStream.close();\n\t\t\t\t}\n\t\t\t\tcatch ( IOException e ) {\n\t\t\t\t\tJAXB_LOGGER.problemClosingSchemaStream( e.toString() );\n\t\t\t\t}\n\t\t\t}","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/xsd/LocalXsdResolver.java#L60-L96","documentation":"LocalXsdResolver loads the XSDs bundled inside hibernate-core (e.g. org/hibernate/xsd/...) by first locating the resource on the classpath via resolveLocalXsdUrl. If no URL can be produced, the resource simply is not visible to Hibernate's classloader, and XsdException('Unable to locate schema [...] via classpath') is thrown naming the missing resource.","triggerScenarios":"resolveLocalXsdSchema(schemaResourceName) called with a bundled schema name that the current ClassLoaderService cannot resolve: shaded/minimized hibernate-core jar from which the xsd resources were stripped, a broken dependency resolution, or a custom ClassLoaderService that hides resources.","commonSituations":"Maven/Gradle shade or proguard/R8 minification removing *.xsd resources from hibernate-core; app-server parent-first classloading isolating Hibernate from its own jar; corrupted or incompletely downloaded hibernate-core artifact; custom classloader service delegating to a loader without hibernate-core.","solutions":["Verify the resource exists in the runtime classpath: inspect the hibernate-core jar for the schema path named in the message.","Stop shade/minimize tools from stripping XSDs (keep org/hibernate/xsd/** resource patterns; do not minimize hibernate-core).","Re-download/replace a corrupted hibernate-core artifact (checksum check) and pin a good version.","If using a custom ClassLoaderService, ensure it can serve Hibernate's own resources, or fix parent-delegation order in the app server."],"exampleFix":"# before\n# shade plugin without resource retention -> xsd files removed from hibernate-core\n<filters><filter><artifact>*:*</artifact><excludes><exclude>**/*.xsd</exclude></excludes></filter></filters>\n\n# after\n# keep Hibernate's bundled schemas in the fat jar\n<filters><filter><artifact>org.hibernate:hibernate-core</artifact><includes><include>**</include></includes></filter></filters>","handlingStrategy":"validation","validationCode":"static boolean hibernateXsdsVisible() {\n    ClassLoader cl = org.hibernate.boot.xsd.LocalXsdResolver.class.getClassLoader();\n    return cl.getResource( \"org/hibernate/xsd/cfg/legacy-configuration-4.0.xsd\" ) != null\n        && cl.getResource( \"org/hibernate/xsd/mapping/orm_4_0.xsd\" ) != null;\n}\n// run as a startup/deploy health check before building the SessionFactory","typeGuard":null,"tryCatchPattern":"try { return LocalXsdResolver.resolveLocalXsdSchema( name ); }\ncatch ( XsdException e ) {\n    if ( e.getMessage().startsWith( \"Unable to locate schema\" ) ) {\n        throw new IllegalStateException( \"hibernate-core jar incomplete - bundled XSDs missing: \" + name, e );\n    }\n    throw e;\n}","preventionTips":["Never strip **/*.xsd when shading/minimizing hibernate-core; test the fat jar's bootstrap in CI.","Add a startup assertion that Hibernate's own resources resolve from the runtime classloader.","Prevent classpath shadowing of org/hibernate/** resources by your own artifacts."],"tags":["hibernate","xsd","classpath","shaded-jar","bootstrap"],"backgroundTag":"classpath-resource-not-found","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}