{"record":{"id":"ccaa37ed30884a42","repo":"apple/pkl","slug":"failed-to-convert-pkl-base-string-to-java-net-u","errorCode":null,"errorMessage":"Failed to convert `pkl.base#String` to `java.net.URI`.","messagePattern":"Failed to convert `pkl\\.base#String` to `java\\.net\\.URI`\\.","errorType":"exception","errorClass":"ConversionException","httpStatus":null,"severity":"error","filePath":"pkl-config-java/src/main/java/org/pkl/config/java/mapper/Conversions.java","lineNumber":144,"sourceCode":"                      \"Cannot convert pkl.base#String `%s` to java.lang.Character because it is not of length 1.\",\n                      value));\n            }\n            return value.charAt(0);\n          });\n\n  /**\n   * Conversion from {@code pkl.base#String} to {@link URI}. Throws {@link ConversionException} if\n   * the String value is not a syntactically valid URI.\n   */\n  public static final Conversion<String, URI> pStringToURI =\n      Conversion.of(\n          PClassInfo.String,\n          URI.class,\n          (value, mapper) -> {\n            try {\n              return new URI(value);\n            } 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);","sourceCodeStart":126,"sourceCodeEnd":162,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-config-java/src/main/java/org/pkl/config/java/mapper/Conversions.java#L126-L162","documentation":"Thrown by Conversions.pStringToUri when mapping a Pkl `pkl.base#String` property to a `java.net.URI` target. The string value does not parse as a valid RFC 2396 URI, so `new URI(value)` throws URISyntaxException, which is wrapped in a ConversionException. This is a value-format error, not a library bug: the Pkl config holds a string that is not a well-formed URI.","triggerScenarios":"Calling JavaMapper/MappingDecoder mapping to a Java type with a `java.net.URI` field (or calling Conversions.pStringToUri directly) where the Pkl string value is malformed — e.g. missing scheme (`\"example.com/x\"`), illegal characters (spaces, unescaped `|`, `{`, `}`), or a malformed scheme/fragment (e.g. `\"http://host:a\"`).","commonSituations":"Config files with endpoint, docs, or repository URLs typed by hand; values interpolated with spaces or unencoded characters; strings like `\"localhost:8080\"` (parsed as scheme 'localhost', invalid SSF) instead of `\"http://localhost:8080\"`.","solutions":["Fix the string value in the Pkl source to be a valid URI: include a proper scheme and percent-encode illegal characters (replace spaces with %20, etc.).","If the value is meant to be a URI reference validated later, map it to String instead of URI and construct the URI in application code where you can control error handling.","Pre-validate with `new URI(value)` (or java.net.URI.create) before mapping to get the exact syntax error index from URISyntaxException.","If the value is actually a file path, map to `java.nio.file.Path` (Conversions.pStringToPath) or use `Paths.get(...).toUri()` instead."],"exampleFix":"// before (pkl)\nendpoint = \"my.service/api:9000\"\n// after (pkl)\nendpoint = \"https://my.service/api:9000\"","handlingStrategy":"validation","validationCode":"try { new java.net.URI(pklStringValue); } catch (java.net.URISyntaxException e) { throw new IllegalStateException(\"Config value is not a valid URI: \" + pklStringValue + \" (\" + e.getReason() + \" at index \" + e.getIndex() + \")\"); }","typeGuard":"static boolean isValidUri(String s) { try { new java.net.URI(s); return true; } catch (java.net.URISyntaxException e) { return false; } }","tryCatchPattern":"try { Uri uri = mapper.map(module, MyConfig.class); } catch (ConversionException e) { log.error(\"Bad URI in config: {}\", e.getCause() != null ? e.getCause().getMessage() : e.getMessage()); }","preventionTips":["Always include a scheme (https://, file:/) in URI config values","Percent-encode spaces and reserved characters","Prefer java.net.URI over java.net.URL for pure syntax validation","Validate config strings at startup, before business logic runs"],"tags":["pkl","java","uri","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-14T16:17:12.679Z"}