{"record":{"id":"ed9bc04d61706e27","repo":"hibernate/hibernate-orm","slug":"unable-to-open-url-inputstream","errorCode":null,"errorMessage":"Unable to open URL InputStream","messagePattern":"Unable to open URL InputStream","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/UrlXmlSource.java","lineNumber":77,"sourceCode":"\t * Create a mapping {@linkplain Binding binding} from a URL\n\t *\n\t * @param url The url from which to read the mapping information\n\t * @param origin Description of the source from which the url came\n\t * @param binder The JAXB binder to use\n\t */\n\tpublic static Binding<? extends JaxbBindableMappingDescriptor> fromUrl(\n\t\t\tURL url,\n\t\t\tOrigin origin,\n\t\t\tMappingBinder binder) {\n\t\tJAXB_LOGGER.tracef( \"Reading mapping document from URL: %s\", origin.getName() );\n\t\ttry {\n\t\t\treturn InputStreamXmlSource.fromStream( url.openStream(), origin, true, binder );\n\t\t}\n\t\tcatch (UnknownHostException e) {\n\t\t\tthrow new MappingNotFoundException( \"Invalid URL\", e, origin );\n\t\t}\n\t\tcatch (IOException e) {\n\t\t\tthrow new MappingException( \"Unable to open URL InputStream\", e, origin );\n\t\t}\n\t}\n}\n","sourceCodeStart":59,"sourceCodeEnd":81,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/UrlXmlSource.java#L59-L81","documentation":"In UrlXmlSource.fromUrl, any IOException from url.openStream() other than UnknownHostException is wrapped as MappingException('Unable to open URL InputStream'). The stream-level open failed: HTTP error status (FileNotFoundException for 404), connection refused, timeout, or an unreadable file: URL.","triggerScenarios":"Configuration.addURL(...) where the server returns 404/403/500 (HttpURLConnection maps 404 to FileNotFoundException), the port is closed (connection refused), a file:// URL points to a missing/unreadable file, or a read timeout fires while the server stalls.","commonSituations":"Mapping served by an HTTP endpoint that is down or firewalled from the application subnet; file URL with wrong path or OS-level permission denied; slow CI network causing connect timeouts during bootstrap.","solutions":["Test the exact URL from the deploy host: 'curl -fO http://host/mappings/item.hbm.xml'","Fix the path (404) or grant read permission (file URLs), or start/unchblock the serving host","Set -Dsun.net.client.defaultConnectTimeout if slow networks cause hangs","Move the mapping into the artifact and load it via addResource to remove the network dependency from bootstrap"],"exampleFix":"// before\nsessionFactoryCfg.addURL(new URL(\"file:/opt/cfg/mapping/item.hbm.xml\")); // file missing\n\n// after: keep mapping inside the jar, no runtime file dependency\nsessionFactoryCfg.addResource(\"mappings/item.hbm.xml\");","handlingStrategy":"try-catch","validationCode":"try (InputStream probe = url.openStream()) {\n    // reachable now; note this is the same operation Hibernate performs, so treat as fail-fast probe\n} catch (IOException e) {\n    throw new IllegalStateException(\"mapping URL not openable: \" + url, e);\n}","typeGuard":null,"tryCatchPattern":"catch (MappingException e) {\n    Throwable c = e.getCause();\n    if (c instanceof java.io.FileNotFoundException) { /* 404 or missing file */ }\n    else if (c instanceof java.net.ConnectException) { /* server down / refused */ }\n    throw new IllegalStateException(\"Cannot open mapping URL \" + url, e);\n}","preventionTips":["Health-check HTTP endpoints serving mappings before startup","Use file:// or classpath mappings to remove network from bootstrap","curl the exact URL from the deploy host during deployment scripts"],"tags":["url","network","io","mapping-file","bootstrap"],"backgroundTag":"url-open-failed","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}