{"record":{"id":"c984177c3d2a745c","repo":"hibernate/hibernate-orm","slug":"stream-error-handling-schema-url-s","errorCode":null,"errorMessage":"Stream error handling schema url [%s]","messagePattern":"Stream error handling schema url \\[(.+?)\\]","errorType":"exception","errorClass":"XsdException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/cfgxml/internal/JaxbCfgProcessor.java","lineNumber":178,"sourceCode":"\t\t\tfinal var schemaStream = url.openStream();\n\t\t\ttry {\n\t\t\t\treturn SchemaFactory.newInstance( schemaLanguage )\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 [\" + schemaName + \"]\", e, schemaName );\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}\n\t\t}\n\t\tcatch ( IOException e ) {\n\t\t\tthrow new XsdException( \"Stream error handling schema url [\" + url.toExternalForm() + \"]\", schemaName );\n\t\t}\n\t}\n\n\tstatic class ContextProvidingValidationEventHandler implements ValidationEventHandler {\n\t\tprivate int lineNumber;\n\t\tprivate int columnNumber;\n\t\tprivate String message;\n\n\t\t@Override\n\t\tpublic boolean handleEvent(ValidationEvent validationEvent) {\n\t\t\tfinal var locator = validationEvent.getLocator();\n\t\t\tlineNumber = locator.getLineNumber();\n\t\t\tcolumnNumber = locator.getColumnNumber();\n\t\t\tmessage = validationEvent.getMessage();\n\t\t\treturn false;\n\t\t}\n\n\t\tpublic int getLineNumber() {","sourceCodeStart":160,"sourceCodeEnd":196,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/cfgxml/internal/JaxbCfgProcessor.java#L160-L196","documentation":"Thrown by Hibernate's cfg.xml processor while it validates hibernate.cfg.xml. After resolving the XML schema (XSD) for the configuration file, opening or reading the schema's InputStream raised an IOException, which Hibernate wraps in an XsdException together with the schema URL. Note that the underlying IOException is not chained into this exception, so the message URL is your main diagnostic. The problem is that the schema itself could not be read, not that your cfg.xml syntax is wrong.","triggerScenarios":"JaxbCfgProcessor resolves the cfg.xml schema to a URL and opens a stream on it; any IOException while obtaining or reading that stream (unreachable remote XSD URL, missing classpath XSD resource, dropped connection, shaded jar that stripped the resource) falls into the catch at JaxbCfgProcessor.java:178 and is rethrown as XsdException.","commonSituations":"Air-gapped or firewalled environments where the schemaLocation forces an HTTP fetch of the XSD; uber-jars/shaded builds that leave hibernate-core's bundled XSD resources behind; a cfg.xml schema reference pointing at a URL that no longer resolves; partial Hibernate upgrades where the referenced schema version is not on the classpath.","solutions":["Drop the remote xsi:schemaLocation and let Hibernate resolve the XSD bundled inside hibernate-core (namespace-only reference)","If you must keep the reference, add an XML catalog / entity resolver so the schema resolves from the classpath with no network fetch","Check proxy and firewall settings when the schema URL is genuinely remote and must be fetched","If building a fat jar, verify hibernate-core's schema resources survived shading and add them back if stripped"],"exampleFix":"<!-- before: schemaLocation forces a remote fetch -->\n<hibernate-configuration xmlns=\"http://www.hibernate.org/xsd/orm/cfg\"\n    xsi:schemaLocation=\"http://www.hibernate.org/xsd/orm/cfg http://www.hibernate.org/xsd/orm/cfg/hibernate-configuration.xsd\">\n\n<!-- after: no remote schemaLocation, Hibernate uses the XSD bundled in hibernate-core -->\n<hibernate-configuration xmlns=\"http://www.hibernate.org/xsd/orm/cfg\">","handlingStrategy":"validation","validationCode":"// Fail fast before Configuration.configure(...)\ntry (InputStream in = new URL(schemaUrl).openStream()) {\n    if (in == null) throw new IllegalStateException(\"cfg.xml schema unreachable: \" + schemaUrl);\n}\ncatch (IOException e) {\n    throw new IllegalStateException(\"Schema URL not readable: \" + schemaUrl\n            + \" - fix offline/proxy setup or use the bundled schema\", e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    SessionFactory sf = new Configuration().configure(\"hibernate.cfg.xml\").buildSessionFactory();\n}\ncatch (XsdException e) {\n    // The schema stream could not be opened/read: take the URL from e.getMessage(),\n    // switch to the classpath-bundled schema or fix network/proxy access\n}","preventionTips":["Reference the XSD bundled in hibernate-core (namespace-only) instead of a remote schemaLocation so no network fetch is needed","In offline CI, use an XML catalog or entity resolver for schema locations","Verify fat/uber-jars retain hibernate-core's schema resources after shading"],"tags":["hibernate","cfg-xml","xsd","io"],"backgroundTag":"xsd-schema-load-failure","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}