apple/pkl · error · VmException

cannotAnalyzeRelativeModuleUri

cannotAnalyzeRelativeModuleUri

Error message

cannotAnalyzeRelativeModuleUri

What it means

After successfully constructing the URI in AnalyNodes.eval, each module URI must be absolute (have a scheme such as `file:`, `https:`, `projectpackage:`). A relative URI like "mod.pkl" cannot be resolved by the analyzer, so it throws `cannotAnalyzeRelativeModuleUri` for that value.

Source

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

  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) {
        throw exceptionBuilder().withCause(e).build();
      }
    }
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Prefix relative paths with the absolute scheme/authority: convert "mod.pkl" to "file:///abs/path/mod.pkl".
2. Resolve relative paths against a base directory before adding them to moduleUris.
3. Check each URI has a scheme (String.contains(":") before the first "/") before invoking the analyzer.

Example fix

// before
moduleUris = List("mod.pkl")
// after
moduleUris = List("file:///home/user/project/mod.pkl")

function isAbsoluteUri(s) {
  return /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(s); // has a scheme
}

When it happens

Trigger: Calling the analyze evaluator with a `moduleUris` entry that parses as a URI but has no scheme — e.g. "mod.pkl" or "../lib/mod.pkl" — hitting the `!uri.isAbsolute()` check at AnalyzeNodes.java:86.

Common situations: Passing plain relative file paths instead of `file:///` absolute URIs, or omitting the scheme when configuring the module set to analyze in tooling that feeds the analyze stdlib module.

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

• cannotHaveRelativeImport
• invalidModuleUri
• Failed to convert `pkl.base#String` to `java.net.URI`.
• invalidUri
• invalidUriMissingFragment

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