{"record":{"id":"8c42e3b62bf72402","repo":"hibernate/hibernate-orm","slug":"stream-error-handling-schema-url-schemaurl","errorCode":null,"errorMessage":"Stream error handling schema url [${schemaUrl}]","messagePattern":"Stream error handling schema url \\[(.+?)\\]","errorType":"exception","errorClass":"XmlInfrastructureException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/stax/LocalSchemaLocator.java","lineNumber":67,"sourceCode":"\t\t\tfinal var schemaStream = schemaUrl.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( schemaUrl.openStream() ) );\n\t\t\t}\n\t\t\tcatch ( Exception e ) {\n\t\t\t\tthrow new XmlInfrastructureException( \"Unable to load schema [\" + schemaUrl.toExternalForm() + \"]\", e );\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 XmlInfrastructureException( \"Stream error handling schema url [\" + schemaUrl.toExternalForm() + \"]\" );\n\t\t}\n\t}\n}\n","sourceCodeStart":49,"sourceCodeEnd":71,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/stax/LocalSchemaLocator.java#L49-L71","documentation":"If schemaUrl.openStream() itself throws IOException, LocalSchemaLocator wraps it as XmlInfrastructureException 'Stream error handling schema url [url]' (note: no cause is attached). The schema URL resolved to something that can no longer be opened — the owning jar/file became unreadable between resolution and open.","triggerScenarios":"The URLClassLoader or JarFile owning the XSD was closed before Hibernate binds mappings (dynamic module unloading, hot-redeploy), the containing file was deleted or its permissions changed, or an OS-level lock (Windows/antivirus) blocks opening the entry.","commonSituations":"Application servers that close child classloaders during redeploy while a cached SessionFactory rebuilds; temporary-file schemas deleted mid-bootstrap; exotic containerized setups with read-only mounts appearing after startup.","solutions":["Ensure hibernate-core's classloader/jar stays open for the whole life of the SessionFactory (rebuild factories after redeploy, not during)","Verify the containing jar/file still exists and is readable at bootstrap: Files.isReadable(Path.of(url.toURI()))","Retry bootstrap in a clean state after a hot redeploy instead of reusing cached metadata objects"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"URL xsd = LocalSchemaLocator.class.getClassLoader().getResource(\"org/hibernate/xsd/mapping/mapping-3.1.xsd\");\nif (xsd == null || !java.nio.file.Files.isReadable(java.nio.file.Path.of(xsd.toURI()))) {\n    throw new IllegalStateException(\"bundled XSD unreadable before bootstrap\");\n}","typeGuard":null,"tryCatchPattern":"catch (XmlInfrastructureException e) {\n    throw new IllegalStateException(\"Schema stream could not be opened - owning jar/classloader may be closed; rebuild in a clean state\", e);\n}","preventionTips":["Keep hibernate-core's classloader open for the SessionFactory lifetime","Rebuild SessionFactory after hot redeploys instead of caching metadata across them"],"tags":["io","xsd","classloader","bootstrap"],"backgroundTag":"resource-stream-open-failed","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}