{"record":{"id":"2d96cf5a89c84d46","repo":"apple/pkl","slug":"failed-to-parse-pkl-module-uri-notation","errorCode":null,"errorMessage":"Failed to parse Pkl module URI: ${notation}","messagePattern":"Failed to parse Pkl module URI: (.+?)","errorType":"validation","errorClass":"InvalidUserDataException","httpStatus":null,"severity":"error","filePath":"pkl-gradle/src/main/java/org/pkl/gradle/utils/PluginUtils.java","lineNumber":89,"sourceCode":"  public static Object parseModuleNotation(Object notation) {\n    if (notation instanceof URI uri) {\n      if (\"file\".equals(uri.getScheme())) {\n        return new File(uri.getPath());\n      }\n      return uri;\n    } else if (notation instanceof File) {\n      return notation;\n    } else if (notation instanceof Path path) {\n      try {\n        return path.toFile();\n      } catch (UnsupportedOperationException e) {\n        throw new InvalidUserDataException(\"Failed to parse Pkl module file path: \" + notation, e);\n      }\n    } 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();","sourceCodeStart":71,"sourceCodeEnd":107,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-gradle/src/main/java/org/pkl/gradle/utils/PluginUtils.java#L71-L107","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Fix the URL string: URL-encode spaces and reserved characters (e.g. use URLEncoder or toUri().toString() from a Path).","Construct URLs via URI/Path APIs instead of string concatenation: File(...).toURI().toURL().","Pass a plain file path (String/File) instead of a URL for local modules.","Check the cause URISyntaxException for the exact offending index/character."],"exampleFix":"// before\nURL u = new URL(\"file:/C:/my dir/mod.pkl\"); // toURI() throws\n// after\nURL u = new File(\"C:/my dir/mod.pkl\").toURI().toURL(); // -> file:/C:/my%20dir/mod.pkl","handlingStrategy":"validation","validationCode":"try { URI(url.toString()) } catch (e: URISyntaxException) { throw InvalidUserDataException(\"Fix URL before passing to pkl config: $url\", e) }","typeGuard":"fun isValidUri(s: String): Boolean = try { URI(s); true } catch (e: URISyntaxException) { false }","tryCatchPattern":"try { parseModuleNotation(url) } catch (InvalidUserDataException e) { if (e.cause is URISyntaxException) logger.error(\"URL-encode the notation: $url\"); throw e }","preventionTips":["Build URLs via File.toURI().toURL() or Path.toUri(), never string concatenation","Percent-encode spaces and reserved characters in paths","Validate URLs with URI() before configuring tasks","Beware interpolated project paths with spaces on Windows/macOS"],"tags":["gradle","pkl","uri","parsing"],"backgroundTag":"invalid-url-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"}