apple/pkl · error · ConversionException

Failed to convert `pkl.base#String` to `java.net.URI`.

Error message

Failed to convert `pkl.base#String` to `java.net.URI`.

What it means

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.

Source

Thrown at pkl-config-java/src/main/java/org/pkl/config/java/mapper/Conversions.java:144

                      "Cannot convert pkl.base#String `%s` to java.lang.Character because it is not of length 1.",
                      value));
            }
            return value.charAt(0);
          });

  /**
   * Conversion from {@code pkl.base#String} to {@link URI}. Throws {@link ConversionException} if
   * the String value is not a syntactically valid URI.
   */
  public static final Conversion<String, URI> pStringToURI =
      Conversion.of(
          PClassInfo.String,
          URI.class,
          (value, mapper) -> {
            try {
              return new URI(value);
            } catch (URISyntaxException e) {
              throw new ConversionException(
                  "Failed to convert `pkl.base#String` to `java.net.URI`.", e);
            }
          });

  /**
   * Conversion from {@code pkl.base#String} to {@link URL}. Throws {@link ConversionException} if
   * the String value is not a syntactically valid URL.
   */
  public static final Conversion<String, URL> pStringToURL =
      Conversion.of(
          PClassInfo.String,
          URL.class,
          (value, mapper) -> {
            try {
              return new URL(value);
            } catch (MalformedURLException e) {
              throw new ConversionException(
                  "Failed to convert `pkl.base#String` to `java.net.URL`.", e);

View on GitHub (pinned to f3efcbfc9b)

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.

Example fix

// before (pkl)
endpoint = "my.service/api:9000"
// after (pkl)
endpoint = "https://my.service/api:9000"

Defensive patterns

Strategy: validation

Validate before calling

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() + ")"); }

Type guard

static boolean isValidUri(String s) { try { new java.net.URI(s); return true; } catch (java.net.URISyntaxException e) { return false; } }

Try / catch

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()); }

Prevention

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

When it happens

Trigger: 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"`).

Common situations: 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"`.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

AI-assisted analysis of apple/pkl@f3efcbfc9b (2026-09-08). Data as JSON: /api/errors/ccaa37ed30884a42. Report an issue: GitHub.