{"record":{"id":"f56971db0d948a93","repo":"hibernate/hibernate-orm","slug":"stream-error-handling-schema-url","errorCode":null,"errorMessage":"Stream error handling schema url [{}]","messagePattern":"Stream error handling schema url \\[(.+?)\\]","errorType":"exception","errorClass":"XsdException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/xsd/LocalXsdResolver.java","lineNumber":99,"sourceCode":"\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}\n\t\t}\n\t\tcatch ( IOException e ) {\n\t\t\tthrow new XsdException( \"Stream error handling schema url [\" + url.toExternalForm() + \"]\", schemaResourceName );\n\t\t}\n\t}\n\n\tpublic static XsdDescriptor buildXsdDescriptor(String resourceName, String version, String namespaceUri) {\n\t\treturn new XsdDescriptor( resourceName, resolveLocalXsdSchema( resourceName ), version, namespaceUri );\n\t}\n}\n","sourceCodeStart":81,"sourceCodeEnd":107,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/xsd/LocalXsdResolver.java#L81-L107","documentation":"After locating the schema URL and entering the loading block, the initial url.openStream() threw an IOException, which the outer catch converts to XsdException('Stream error handling schema url [...]') including the external form of the URL. The resource was resolvable as a URL, but the stream could not be opened at all - a connection/I-O level failure rather than a parse failure.","triggerScenarios":"resolveLocalXsdSchema() where url.openStream() fails: jar/entry deleted or replaced between resolution and opening, URL pointing at a remote/unreachable location, or a jar protocol handler denied by the environment (e.g. sealed runtime, security manager, sandboxed FS).","commonSituations":"Hot-redeploy or parallel build deleting/rewriting the jar that contains the schema while Hibernate bootstraps; custom URL schemes registered for the classpath; restrictive containers blocking jar: or file: access; NFS/cloud-mounted artifact caches with transient I/O errors.","solutions":["Check the URL in the message and open it manually (curl/unzip) to see whether the entry truly exists and is readable in the failing environment.","For intermittent I/O on shared caches, retry after warming/re-downloading artifacts; pin artifacts locally to avoid mid-boot rewrites.","Avoid redeploys that mutate classpath jars during startup (staging the new jar then switching atomically).","If a custom protocol handler is involved, ensure it supports openStream() or fall back to standard jar/file protocols."],"exampleFix":"// before\n// jar replaced while SessionFactory builds -> url.openStream() throws IOException\nnew SchemaFactory... // bootstrap fails with 'Stream error handling schema url [jar:file:...hibernate-core.jar!/...]'\n\n// after\n// stage artifacts immutably and build from a stable classpath\ncp $(readlink -f libs/hibernate-core.jar):... com.acme.App\n// verify readability before boot:\ntry ( var in = url.openStream() ) { in.readAllBytes(); }","handlingStrategy":"try-catch","validationCode":"static boolean schemaStreamOpenable(String resource) {\n    URL url = Thread.currentThread().getContextClassLoader().getResource( resource );\n    if ( url == null ) return false;\n    try ( var ignored = url.openStream() ) { return true; }\n    catch ( IOException e ) { return false; }\n}","typeGuard":null,"tryCatchPattern":"try { return LocalXsdResolver.resolveLocalXsdSchema( name ); }\ncatch ( XsdException e ) {\n    if ( e.getMessage().startsWith( \"Stream error handling schema url\" ) ) {\n        // I/O-level failure on the resolved URL: stale/rewritten jar, unreadable entry, FS error\n        retryOnceAfterRefreshingArtifacts( name ); // then rethrow if it persists\n    }\n    throw e;\n}","preventionTips":["Keep the classpath immutable during startup - do not rewrite jars a running bootstrap is reading.","Use stable, read-only artifact caches in CI (content-addressed) to avoid mid-read cache mutation.","Health-check critical classpath resources (resolve + openStream) before bootstrap in restrictive environments."],"tags":["hibernate","xsd","io","classpath","schema"],"backgroundTag":"resource-stream-io-error","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}