apple/pkl · error · ConversionException

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

Error message

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

What it means

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.

Source

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

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

  /** Conversion from {@code pkl.base#String} to {@link File}. */
  public static final Conversion<String, File> pStringToFile =
      Conversion.of(PClassInfo.String, File.class, (value, mapper) -> new File(value));

  /**
   * Conversion from {@code pkl.base#String} to {@link Path}. Throws {@link ConversionException} if
   * the String value is not a syntactically valid path.
   */
  public static final Conversion<String, Path> pStringToPath =
      Conversion.of(
          PClassInfo.String,
          Path.class,
          (value, mapper) -> {
            try {

View on GitHub (pinned to f3efcbfc9b)

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.

Example fix

// before (pkl)
repo = "github.com/apple/pkl"
// after (pkl)
repo = "https://github.com/apple/pkl"

Defensive patterns

Strategy: validation

Validate before calling

try { new java.net.URL(pklStringValue); } catch (java.net.MalformedURLException e) { throw new IllegalStateException("Config value is not a valid URL: " + pklStringValue + " (" + e.getMessage() + ")"); }

Type guard

static boolean isValidUrl(String s) { try { new java.net.URL(s); return true; } catch (java.net.MalformedURLException e) { return false; } }

Try / catch

try { MyConfig cfg = mapper.map(module, MyConfig.class); } catch (ConversionException e) { log.error("Malformed URL in config: {}", e.getMessage()); throw new ConfigException(e); }

Prevention

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

When it happens

Trigger: 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.

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

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/a11607fdd1cbac76. Report an issue: GitHub.