apple/pkl · error · ConversionException

Failed to convert `pkl.base#String` to `java.nio.file.Path`.

Error message

Failed to convert `pkl.base#String` to `java.nio.file.Path`.

What it means

Thrown by Conversions.pStringToPath when mapping a Pkl `pkl.base#String` to a `java.nio.file.Path`. The string cannot be converted into a platform path by `Path.of(value)` — it throws InvalidPathException — so it is wrapped in a ConversionException. This typically means the string contains characters illegal in paths on the current filesystem/OS.

Source

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

          });

  /** 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 {
              return Path.of(value);
            } catch (InvalidPathException e) {
              throw new ConversionException(
                  "Failed to convert `pkl.base#String` to `java.nio.file.Path`.", e);
            }
          });

  /** Conversion from {@code pkl.base#String} to {@link Pattern}. */
  public static final Conversion<String, Pattern> pStringToPattern =
      Conversion.of(
          PClassInfo.String,
          Pattern.class,
          (value, mapper) -> {
            try {
              return Pattern.compile(value);
            } catch (PatternSyntaxException e) {
              throw new ConversionException(
                  "Failed to convert `pkl.base#String` to `java.util.regex.Pattern`.", e);
            }
          });

View on GitHub (pinned to f3efcbfc9b)

Solutions

Correct the string in the Pkl config so it is a valid path for the target OS (remove/escape illegal characters).
If the value is a URI like `file:///var/log`, convert with `Paths.get(URI.create(value))` in app code rather than mapping the raw string to Path.
Pre-validate with `Paths.get(value)` in a try/catch to surface the exact InvalidPathException before mapping.
Normalize path separators with forward slashes or `Path.of(...)`-safe forms so configs are portable across OSes.

Example fix

// before (pkl)
logFile = "C:\\data:logs\\app.log" // ':' illegal in Windows filename
// after (pkl)
logFile = "C:\\data\\logs\\app.log"

Defensive patterns

Strategy: validation

Validate before calling

try { java.nio.file.Path p = java.nio.file.Path.of(pklStringValue); } catch (java.nio.file.InvalidPathException e) { throw new IllegalStateException("Config value is not a valid path: " + pklStringValue); }

Type guard

static boolean isValidPath(String s) { try { java.nio.file.Path.of(s); return true; } catch (java.nio.file.InvalidPathException e) { return false; } }

Try / catch

try { MyConfig cfg = mapper.map(module, MyConfig.class); } catch (ConversionException e) { throw new IllegalArgumentException("Invalid file path in config", e.getCause()); }

Prevention

Avoid characters illegal on the target OS (e.g. ':' or '<>|"*?' on Windows)
Pass plain paths, not file:// URI strings, to Path fields
Use forward slashes or Path-normalized strings for cross-platform configs
Check for NUL or control characters in user-supplied paths

When it happens

Trigger: Mapping to a target type with a `java.nio.file.Path` field (or calling Conversions.pStringToPath directly) where the Pkl string contains NUL bytes, illegal characters on Windows (`<`, `>`, `|`, `"`, `*`, `?`, `:` in the wrong place), or is a URI/URL string passed to a path field.

Common situations: Config written on Linux (with `:` in filenames) run on Windows; a `file:///...` URI string pasted where a plain path is expected; values containing quotes or wildcard characters.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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