{"record":{"id":"b49bf707c584a5ce","repo":"apple/pkl","slug":"failed-to-parse-pkl-module-file-path-s","errorCode":null,"errorMessage":"Failed to parse Pkl module file path: ${s}","messagePattern":"Failed to parse Pkl module file path: (.+?)","errorType":"validation","errorClass":"InvalidUserDataException","httpStatus":null,"severity":"error","filePath":"pkl-gradle/src/main/java/org/pkl/gradle/utils/PluginUtils.java","lineNumber":103,"sourceCode":"    } else if (notation instanceof URL url) {\n      try {\n        return parseModuleNotation(url.toURI());\n      } catch (URISyntaxException e) {\n        throw new InvalidUserDataException(\"Failed to parse Pkl module URI: \" + notation, e);\n      }\n    } else if (notation instanceof CharSequence) {\n      var s = notation.toString();\n      if (IoUtils.isUriLike(s)) {\n        try {\n          return parseModuleNotation(IoUtils.toUri(s));\n        } catch (URISyntaxException e) {\n          throw new InvalidUserDataException(\"Failed to parse Pkl module URI: \" + s, e);\n        }\n      } else {\n        try {\n          return Paths.get(s).toFile();\n        } catch (InvalidPathException | UnsupportedOperationException e) {\n          throw new InvalidUserDataException(\"Failed to parse Pkl module file path: \" + s, e);\n        }\n      }\n    } else if (notation instanceof FileSystemLocation location) {\n      return location.getAsFile();\n    } else {\n      throw new InvalidUserDataException(\n          \"Unsupported value of type \"\n              + notation.getClass()\n              + \" used as a module path: \"\n              + notation);\n    }\n  }\n\n  /**\n   * Converts either a file or a URI to a URI. We convert a relative file to a URI via the {@link\n   * IoUtils#createUri(String)} because other ways of conversion can make relative paths into\n   * absolute URIs, which may break module loading.\n   */","sourceCodeStart":85,"sourceCodeEnd":121,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-gradle/src/main/java/org/pkl/gradle/utils/PluginUtils.java#L85-L121","documentation":"parseModuleNotation accepts a String notation for a Pkl module. If the string is not a valid URI it falls back to interpreting it as a filesystem path; when Paths.get(s) throws InvalidPathException or UnsupportedOperationException, the library wraps it in this InvalidUserDataException so Gradle reports which notation string could not be parsed.","triggerScenarios":"Passing a String to a Pkl Gradle plugin module property (e.g. pkl project/module configuration) that contains characters illegal in a filesystem path, such as a NUL byte, or a URI-formatted string on a platform whose Path implementation rejects it (UnsupportedOperationException from Paths.get).","commonSituations":"Typos or unescaped characters in pklModulePath/pklModule URIs, copy-pasting a URI into a field expected to be a path, Windows path handling with unusual characters, or generating notation strings programmatically with embedded nulls.","solutions":["Fix the notation string so it is either a valid module URI (e.g. pkl:, https:, file:) or a valid filesystem path for the OS","Use a java.io.File or FileSystemLocation (project.layout.files/projectDir.resolve(...)) notation instead of a raw String","Check the string for illegal characters (NUL bytes, invalid separators) before passing it","Print/log the offending notation (it is included in the message) and correct it in build scripts or task inputs"],"exampleFix":"// before\npklModules = listOf(\"pkl:base?\\u0000\")\n// after\npklModules = listOf(\"pkl:base\")","handlingStrategy":"validation","validationCode":"// Java/Gradle\nstatic boolean isValidNotation(String s) {\n  try { java.nio.file.Paths.get(s); return true; }\n  catch (java.nio.file.InvalidPathException | UnsupportedOperationException e) { return false; }\n}\n// call before assigning: if (!isValidNotation(notation)) throw new IllegalArgumentException(...);","typeGuard":"static boolean isSafeModuleNotation(Object n) {\n  return n instanceof String s && isValidNotation(s) || n instanceof java.io.File || n instanceof org.gradle.api.file.FileSystemLocation;\n}","tryCatchPattern":"try {\n  file = PluginUtils.parseModuleNotation(notation);\n} catch (InvalidUserDataException e) {\n  logger.error(\"Bad Pkl module notation: {}\", e.getMessage());\n  throw new GradleException(\"Fix module notation: \" + notation, e);\n}","preventionTips":["Validate notation strings (no NUL/illegal path chars) before passing to Pkl tasks","Prefer File or FileSystemLocation notations over raw strings","Keep URIs and paths distinct in build configuration; don't paste URIs into path fields"],"tags":["gradle","path-parsing","invalid-path","configuration"],"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-17T15:17:12.973Z"}