{"record":{"id":"6b715378e2e2cfed","repo":"hibernate/hibernate-orm","slug":"invalid-url","errorCode":null,"errorMessage":"Invalid URL","messagePattern":"Invalid URL","errorType":"exception","errorClass":"MappingNotFoundException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/UrlXmlSource.java","lineNumber":74,"sourceCode":"\t}\n\n\t/**\n\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":56,"sourceCodeEnd":81,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/UrlXmlSource.java#L56-L81","documentation":"When opening a URL-based mapping, UrlXmlSource.fromUrl catches UnknownHostException specifically and throws MappingNotFoundException('Invalid URL'). It means the host part of the URL could not be resolved by DNS at bootstrap time — the URL syntax parsed, but the name lookup failed.","triggerScenarios":"Configuration.addURL(new URL(\"http://db.acme.internal/mappings/item.hbm.xml\")) where the hostname does not resolve: typo'd host, internal DNS name unreachable from the deployment network, offline/air-gapped environment, or missing proxy configuration for HTTP-based mapping URLs.","commonSituations":"Mappings served over HTTP in environments with strict DNS; hostname valid in dev but not in the production subnet; JVM proxy properties (http.proxyHost) not set so the name is resolved locally and fails.","solutions":["Verify name resolution on the deploy host: 'nslookup db.acme.internal' or InetAddress.getByName(host) in the same JVM","Fix the hostname in the URL or add the host to DNS/hosts file","Configure JVM proxy settings (-Dhttp.proxyHost/-Dhttp.proxyPort) if resolution goes through a proxy","Prefer packaging the mapping inside the app and using addResource/addClass instead of a remote HTTP URL"],"exampleFix":"// before\nsessionFactoryCfg.addURL(new URL(\"http://acme-intrenal/mappings/item.hbm.xml\")); // typo\n\n// after\nsessionFactoryCfg.addURL(new URL(\"http://acme-internal/mappings/item.hbm.xml\"));","handlingStrategy":"validation","validationCode":"URL url = new URL(\"http\", host, port, path);\ntry {\n    InetAddress.getByName(url.getHost()); // throws UnknownHostException early, with a clearer message\n} catch (UnknownHostException e) {\n    throw new IllegalStateException(\"mapping host unresolvable: \" + url.getHost(), e);\n}\nsessionFactoryCfg.addURL(url);","typeGuard":null,"tryCatchPattern":"catch (MappingNotFoundException e) {\n    if (\"Invalid URL\".equals(e.getMessage())) {\n        throw new IllegalStateException(\"Host in mapping URL cannot be resolved - check DNS/proxy for the bootstrap host\", e);\n    }\n    throw e;\n}","preventionTips":["Prefer packaging mappings inside the application over remote URLs","Verify hostname resolution on the actual deploy host, not a developer laptop","Configure -Dhttp.proxyHost/-Dhttp.proxyPort when HTTP mappings sit behind a proxy"],"tags":["url","network","dns","mapping-file","bootstrap"],"backgroundTag":"unknown-host","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}