{"record":{"id":"a11607fdd1cbac76","repo":"apple/pkl","slug":"failed-to-convert-pkl-base-string-to-java-net-u-a11607","errorCode":null,"errorMessage":"Failed to convert `pkl.base#String` to `java.net.URL`.","messagePattern":"Failed to convert `pkl\\.base#String` to `java\\.net\\.URL`\\.","errorType":"exception","errorClass":"ConversionException","httpStatus":null,"severity":"error","filePath":"pkl-config-java/src/main/java/org/pkl/config/java/mapper/Conversions.java","lineNumber":161,"sourceCode":"            } catch (URISyntaxException e) {\n              throw new ConversionException(\n                  \"Failed to convert `pkl.base#String` to `java.net.URI`.\", e);\n            }\n          });\n\n  /**\n   * Conversion from {@code pkl.base#String} to {@link URL}. Throws {@link ConversionException} if\n   * the String value is not a syntactically valid URL.\n   */\n  public static final Conversion<String, URL> pStringToURL =\n      Conversion.of(\n          PClassInfo.String,\n          URL.class,\n          (value, mapper) -> {\n            try {\n              return new URL(value);\n            } catch (MalformedURLException e) {\n              throw new ConversionException(\n                  \"Failed to convert `pkl.base#String` to `java.net.URL`.\", e);\n            }\n          });\n\n  /** Conversion from {@code pkl.base#String} to {@link File}. */\n  public static final Conversion<String, File> pStringToFile =\n      Conversion.of(PClassInfo.String, File.class, (value, mapper) -> new File(value));\n\n  /**\n   * Conversion from {@code pkl.base#String} to {@link Path}. Throws {@link ConversionException} if\n   * the String value is not a syntactically valid path.\n   */\n  public static final Conversion<String, Path> pStringToPath =\n      Conversion.of(\n          PClassInfo.String,\n          Path.class,\n          (value, mapper) -> {\n            try {","sourceCodeStart":143,"sourceCodeEnd":179,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-config-java/src/main/java/org/pkl/config/java/mapper/Conversions.java#L143-L179","documentation":"Thrown by Conversions.pStringToUrl when mapping a Pkl `pkl.base#String` property to a `java.net.URL` target. The string is not a syntactically valid URL for java.net.URL's protocol handlers, so `new URL(value)` throws MalformedURLException, wrapped in a ConversionException. java.net.URL additionally requires a known protocol handler, so even well-formed strings with unknown schemes fail.","triggerScenarios":"Mapping to a target type with a `java.net.URL` field (or calling Conversions.pStringToUrl directly) where the Pkl string has no protocol (`\"example.com/api\"`), an unknown protocol (`\"ftp2://...\"` with no handler), or invalid characters like spaces.","commonSituations":"Hand-written URLs in config missing the `http(s)://` prefix; internal custom schemes not registered with URL.setURLStreamHandlerFactory; copy-pasted URLs containing spaces or full-width characters.","solutions":["Add or correct the protocol prefix in the Pkl value (e.g. `\"https://example.com/api\"`).","If a custom scheme is intended, register a URLStreamHandler for it before mapping, or map to URI/String instead and resolve the URL in app code.","Pre-validate with `new URL(value)` before mapping to see the exact MalformedURLException message.","Prefer `java.net.URI` mapping (pStringToUri) if you only need URL syntax without protocol handler resolution."],"exampleFix":"// before (pkl)\nrepo = \"github.com/apple/pkl\"\n// after (pkl)\nrepo = \"https://github.com/apple/pkl\"","handlingStrategy":"validation","validationCode":"try { new java.net.URL(pklStringValue); } catch (java.net.MalformedURLException e) { throw new IllegalStateException(\"Config value is not a valid URL: \" + pklStringValue + \" (\" + e.getMessage() + \")\"); }","typeGuard":"static boolean isValidUrl(String s) { try { new java.net.URL(s); return true; } catch (java.net.MalformedURLException e) { return false; } }","tryCatchPattern":"try { MyConfig cfg = mapper.map(module, MyConfig.class); } catch (ConversionException e) { log.error(\"Malformed URL in config: {}\", e.getMessage()); throw new ConfigException(e); }","preventionTips":["Always include a supported protocol prefix (http://, https://, file:/)","Register URLStreamHandlers for custom schemes before mapping","Use URI mapping when protocol handler availability is uncertain","Trim whitespace from values before mapping"],"tags":["pkl","java","url","conversion","value-format"],"backgroundTag":"invalid-url-format","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}