apple/pkl · error · InvalidUserDataException

Failed to parse Pkl module URI: ${notation}

Error message

Failed to parse Pkl module URI: ${notation}

What it means

When parseModuleNotation receives a URL notation, it converts it with url.toURI() and recurses; a URISyntaxException there (malformed URL, e.g. containing spaces or illegal characters) is wrapped in InvalidUserDataException with "Failed to parse Pkl module URI: <notation>". This validates module URI notations early in Gradle configuration.

Source

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

  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();
        } 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();

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Fix the URL string: URL-encode spaces and reserved characters (e.g. use URLEncoder or toUri().toString() from a Path).
2. Construct URLs via URI/Path APIs instead of string concatenation: File(...).toURI().toURL().
3. Pass a plain file path (String/File) instead of a URL for local modules.
4. Check the cause URISyntaxException for the exact offending index/character.

Example fix

// before
URL u = new URL("file:/C:/my dir/mod.pkl"); // toURI() throws
// after
URL u = new File("C:/my dir/mod.pkl").toURI().toURL(); // -> file:/C:/my%20dir/mod.pkl

try { URI(url.toString()) } catch (e: URISyntaxException) { throw InvalidUserDataException("Fix URL before passing to pkl config: $url", e) }

fun isValidUri(s: String): Boolean = try { URI(s); true } catch (e: URISyntaxException) { false }

try { parseModuleNotation(url) } catch (InvalidUserDataException e) { if (e.cause is URISyntaxException) logger.error("URL-encode the notation: $url"); throw e }

When it happens

Trigger: Passing a java.net.URL with an invalid/syntactically broken URI form as a module notation; URLs constructed from unencoded user input (spaces, braces, unescaped characters) so toURI() throws URISyntaxException.

Common situations: Building file URLs by string concatenation without encoding; project paths with spaces on Windows/macOS interpolated into URLs; credentials or query strings with reserved characters left unescaped.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

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

Related errors

• Failed to parse Pkl module URI: ${s}
• Failed to convert `pkl.base#String` to `java.net.URI`.
• `%s` is too large to fit into a Version.
• `%s` could not be parsed as a semantic version number.
• invalidUri

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