{"record":{"id":"688305007e780a38","repo":"apple/pkl","slug":"failed-to-convert-pkl-base-string-to-java-nio-f","errorCode":null,"errorMessage":"Failed to convert `pkl.base#String` to `java.nio.file.Path`.","messagePattern":"Failed to convert `pkl\\.base#String` to `java\\.nio\\.file\\.Path`\\.","errorType":"exception","errorClass":"ConversionException","httpStatus":null,"severity":"error","filePath":"pkl-config-java/src/main/java/org/pkl/config/java/mapper/Conversions.java","lineNumber":182,"sourceCode":"          });\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 {\n              return Path.of(value);\n            } catch (InvalidPathException e) {\n              throw new ConversionException(\n                  \"Failed to convert `pkl.base#String` to `java.nio.file.Path`.\", e);\n            }\n          });\n\n  /** Conversion from {@code pkl.base#String} to {@link Pattern}. */\n  public static final Conversion<String, Pattern> pStringToPattern =\n      Conversion.of(\n          PClassInfo.String,\n          Pattern.class,\n          (value, mapper) -> {\n            try {\n              return Pattern.compile(value);\n            } catch (PatternSyntaxException e) {\n              throw new ConversionException(\n                  \"Failed to convert `pkl.base#String` to `java.util.regex.Pattern`.\", e);\n            }\n          });\n","sourceCodeStart":164,"sourceCodeEnd":200,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-config-java/src/main/java/org/pkl/config/java/mapper/Conversions.java#L164-L200","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before (pkl)\nlogFile = \"C:\\\\data:logs\\\\app.log\" // ':' illegal in Windows filename\n// after (pkl)\nlogFile = \"C:\\\\data\\\\logs\\\\app.log\"","handlingStrategy":"validation","validationCode":"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); }","typeGuard":"static boolean isValidPath(String s) { try { java.nio.file.Path.of(s); return true; } catch (java.nio.file.InvalidPathException e) { return false; } }","tryCatchPattern":"try { MyConfig cfg = mapper.map(module, MyConfig.class); } catch (ConversionException e) { throw new IllegalArgumentException(\"Invalid file path in config\", e.getCause()); }","preventionTips":["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"],"tags":["pkl","java","path","conversion","value-format"],"backgroundTag":"invalid-argument-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"}