apple/pkl · error · InvalidUserDataException

Failed to parse Pkl module file path: ${notation}

Error message

Failed to parse Pkl module file path: ${notation}

What it means

PluginUtils.parseModuleNotation converts Gradle dependency notations (String, File, Path, URL, URI) into a java.io.File for Pkl module sources. When the notation is a java.nio.Path whose toFile() fails with UnsupportedOperationException (e.g. a non-default filesystem provider), it throws InvalidUserDataException with the notation embedded. The cause chain preserves the original exception.

Source

Thrown at pkl-gradle/src/main/java/org/pkl/gradle/utils/PluginUtils.java:83

   * method returns a {@link File} corresponding to the file path in the URI. Otherwise, a {@link
   * URI} instance is returned.
   *
   * @throws InvalidUserDataException In case the input is none of the types described above, or
   *     when the underlying value cannot be parsed correctly.
   */
  public static Object parseModuleNotation(Object notation) {
    if (notation instanceof URI uri) {
      if ("file".equals(uri.getScheme())) {
        return new File(uri.getPath());
      }
      return uri;
    } else if (notation instanceof File) {
      return notation;
    } else if (notation instanceof Path path) {
      try {
        return path.toFile();
      } catch (UnsupportedOperationException e) {
        throw new InvalidUserDataException("Failed to parse Pkl module file path: " + notation, e);
      }
    } else if (notation instanceof URL url) {
      try {
        return parseModuleNotation(url.toURI());
      } catch (URISyntaxException e) {
        throw new InvalidUserDataException("Failed to parse Pkl module URI: " + notation, e);
      }
    } else if (notation instanceof CharSequence) {
      var s = notation.toString();
      if (IoUtils.isUriLike(s)) {
        try {
          return parseModuleNotation(IoUtils.toUri(s));
        } catch (URISyntaxException e) {
          throw new InvalidUserDataException("Failed to parse Pkl module URI: " + s, e);
        }
      } else {
        try {
          return Paths.get(s).toFile();

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Convert to a real filesystem path first: copy the file to the default filesystem and pass its path.
2. Pass a java.io.File or an absolute String path on the default filesystem instead of a custom-FS Path.
3. Use a URI notation for remote resources rather than a zipfs Path.
4. Inspect the cause to confirm it is UnsupportedOperationException from toFile().

Example fix

// before
Files.newFileSystem(zip).getPath("/mod.pkl") // passed as notation -> throws
// after
File extracted = File.createTempFile("mod", ".pkl");
Files.copy(zipPath, extracted.toPath(), StandardCopyOption.REPLACE_EXISTING);
// pass `extracted` as the notation

if (notation is Path && notation.fileSystem != FileSystems.getDefault()) {
  throw InvalidUserDataException("Path is on a non-default filesystem: $notation")
}

fun toLocalFile(p: Path): File? = if (p.fileSystem == FileSystems.getDefault()) p.toFile() else null

try { file = PluginUtils.parseModuleNotation(notation) } catch (InvalidUserDataException e) { logger.error("Module notation ${notation} must be on the default filesystem; copy it out first"); throw e }

When it happens

Trigger: Passing a Path created from a custom/non-default FileSystem (e.g. zipfs or an in-memory filesystem) as a module notation to the pkl Gradle configuration; Path.toFile() throwing UnsupportedOperationException.

Common situations: Programmatically building module lists from a zip filesystem (FileSystems.newFileSystem on a jar/zip); test code using Jimfs/MemoryFS and passing those Paths to the plugin; copying paths between filesystems.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Failed to convert `pkl.base#String` to `java.nio.file.Path`.
• Is a directory
• missingPathInPackageUri
• cannotFindModule
• No source modules specified.

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