apple/pkl · error · VmException

invalidModuleUri

invalidModuleUri

Error message

invalidModuleUri

What it means

AnalyzeNodes.eval (part of Pkl's `analyze` standard-library module) converts each entry of the `moduleUris` argument to a java.net.URI. If the string is not syntactically valid URI (per RFC 2396 as enforced by java.net.URI), it throws the `invalidModuleUri` eval error, attaching the underlying URISyntaxException message as a hint.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/stdlib/analyze/AnalyzeNodes.java:80

                var builder = VmMap.builder();
                for (var entry : graph.resolvedImports().entrySet()) {
                  builder.add(entry.getKey().toString(), entry.getValue().toString());
                }
                return builder.build();
              });

  public abstract static class importGraph extends ExternalMethod1Node {
    @Specialization
    @TruffleBoundary
    protected Object eval(@SuppressWarnings("unused") VmTyped self, VmSet moduleUris) {
      var uris = new URI[moduleUris.getLength()];
      var idx = 0;
      for (var moduleUri : moduleUris) {
        URI uri;
        try {
          uri = new URI((String) moduleUri);
        } catch (URISyntaxException e) {
          throw exceptionBuilder()
              .evalError("invalidModuleUri", moduleUri)
              .withHint(e.getMessage())
              .build();
        }
        if (!uri.isAbsolute()) {
          throw exceptionBuilder().evalError("cannotAnalyzeRelativeModuleUri", moduleUri).build();
        }
        uris[idx] = uri;
        idx++;
      }
      var context = VmContext.get(this);
      try {
        var results = VmImportAnalyzer.analyze(uris, context);
        return importGraphFactory.create(results);
      } catch (IOException
          | SecurityManagerException
          | PackageLoadError
          | ExternalReaderProcessException e) {

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Percent-encode the string before constructing the URI (e.g. via URLEncoder or encoding spaces as %20).
2. Convert plain file paths to proper `file:///` URIs.
3. Remove or escape illegal URI characters ({, }, |, \, ^, spaces).
4. Read the hint in the error message — it contains the exact URISyntaxException from java.net.URI.

Example fix

// before
moduleUris = List("C:\my dir\mod.pkl")
// after
moduleUris = List("file:///C:/my%20dir/mod.pkl")

// Java: validate each module URI string
try {
  URI u = new URI(s);
  if (!u.isAbsolute()) throw new IllegalArgumentException("relative: " + s);
} catch (URISyntaxException e) { /* reject */ }

try {
  result = analyzer.eval(moduleUris);
} catch (VmException e) {
  if (e.getMessage().contains("invalidModuleUri")) {
    // fix/encode the offending URI and retry once
  } else throw e;
}

When it happens

Trigger: Calling the analyze evaluator (AnalyzeNodes eval) with a `moduleUris` list containing a string that java.net.URI rejects — e.g. containing spaces, illegal characters like `{`, unmatched `%`, or a bare `#fragment` — at AnalyzeNodes.java:80.

Common situations: Passing unencoded Windows paths ("C:\dir\mod.pkl"), URIs with unencoded spaces, or file paths pasted from a shell into the moduleUris list instead of proper `file:///` URIs.

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.

Related errors

• cannotAnalyzeRelativeModuleUri
• Failed to convert `pkl.base#String` to `java.net.URI`.
• invalidUri
• invalidUriMissingFragment
• cannotHaveRelativeFragment

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