apple/pkl · error · InvalidUserDataException

Unsupported value of type

Error message

Unsupported value of type ${notation.getClass()} used as a module path: ${notation}

What it means

parseModuleNotation only supports String, File, and FileSystemLocation notations. Any other object type reaches the final else branch and throws this InvalidUserDataException naming the actual class and value, so users know their module notation type is unsupported.

Solutions

Convert the value: use toString() for URIs, .toFile() for Path, .asFile for RegularFile, or .get() for Provider
Use File or FileSystemLocation via project.objects/fileProperty APIs as the notation
Check the plugin's supported module notation types and match them in build scripts
If using lazy configuration, resolve with .get() before assigning or use the plugin's Property<FileSystemLocation>-typed accessors

Example fix

// before
pklModule = project.uri("https://example.com/x.pkl")
// after
pklModule = project.uri("https://example.com/x.pkl").toString()

Defensive patterns

Strategy: type-guard

Validate before calling

// before assigning a module notation:
if (!(v instanceof String || v instanceof java.io.File || v instanceof org.gradle.api.file.FileSystemLocation)) {
  throw new IllegalArgumentException("Unsupported module notation type: " + v.getClass());
}

Type guard

static boolean isSupportedModuleNotation(Object n) {
  return n instanceof String || n instanceof java.io.File || n instanceof org.gradle.api.file.FileSystemLocation;
}

Try / catch

try {
  file = PluginUtils.parseModuleNotation(notation);
} catch (InvalidUserDataException e) {
  logger.error("Unsupported module notation: {}", e.getMessage());
  throw new GradleException("Convert notation to File/FileSystemLocation", e);
}

Prevention

Only assign String, File, or FileSystemLocation values to Pkl module properties
Unwrap Provider/RegularFile values with .get()/.asFile before assignment
Convert URI/Path objects explicitly (toString()/toFile())

When it happens

Trigger: Passing an unsupported object (e.g. a URI, Path, RegularFile, GString resolved late, Provider, or arbitrary object) where a module notation (String/File/FileSystemLocation) is expected in Pkl Gradle plugin configuration.

Common situations: Using project.uri(...) or files(...) results assigned into module properties without conversion, passing a Provider that was not unwrapped, or Kotlin/Gradle DSL type confusion when configuring the Pkl plugin.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

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

    } 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();
        } catch (InvalidPathException | UnsupportedOperationException e) {
          throw new InvalidUserDataException("Failed to parse Pkl module file path: " + s, e);
        }
      }
    } else if (notation instanceof FileSystemLocation location) {
      return location.getAsFile();
    } else {
      throw new InvalidUserDataException(
          "Unsupported value of type "
              + notation.getClass()
              + " used as a module path: "
              + notation);
    }
  }

  /**
   * Converts either a file or a URI to a URI. We convert a relative file to a URI via the {@link
   * IoUtils#createUri(String)} because other ways of conversion can make relative paths into
   * absolute URIs, which may break module loading.
   */
  public static URI parsedModuleNotationToUri(Object notation) {
    if (notation instanceof File file) {
      if (file.isAbsolute()) {
        return file.toPath().toUri();
      }
      return IoUtils.createUri(IoUtils.toNormalizedPathString(file.toPath()));

View on GitHub (pinned to f3efcbfc9b)