apple/pkl · error

invalidModuleUri

invalidModuleUri

Error message

invalidModuleUri

What it means

Thrown when the `uri` string of an import (e.g. an entry in the `imports` mapping of a pkl test or command context) cannot be parsed as a URI or path. Java's URISyntaxException is caught in handleImport and re-raised as invalidModuleUri with the offending string and a hint describing the syntax problem.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/runtime/CommandSpecParser.java:1169

  private Object handleImport(VmTyped mport, URI workingDirUri) {
    var moduleName = (String) VmUtils.readMember(mport, Identifier.URI);
    String uriString;
    // Ported from org.pkl.cli.commons.cli.commands.BaseOptions:
    try {
      // Can't just use URI constructor, because URI(null, null, "C:/foo/bar", null) turns
      // into `URI("C", null, "/foo/bar", null)`.
      @SuppressWarnings("DuplicateExpressions")
      var uri =
          IoUtils.isUriLike(moduleName)
              ? new URI(moduleName)
              : IoUtils.isWindows() && IoUtils.isWindowsAbsolutePath(moduleName)
                  ? Path.of(moduleName).toUri()
                  : new URI(null, null, IoUtils.toNormalizedPathString(Path.of(moduleName)), null);
      uriString =
          uri.isAbsolute() ? uri.toString() : IoUtils.resolve(workingDirUri, uri).toString();
    } catch (URISyntaxException e) {
      throw exceptionBuilder()
          .evalError("invalidModuleUri", moduleName)
          .withHint(e.getReason())
          .build();
    }

    var isGlob = (Boolean) VmUtils.readMember(mport, Identifier.GLOB);
    var importUri = URI.create(uriString);
    var language = VmLanguage.get(null);

    // non-glob
    if (!isGlob) {
      var moduleKey = moduleResolver.resolve(importUri);
      return language.loadModule(moduleKey);
    }

    // glob
    var globModuleKey = moduleResolver.resolve(importUri);

View on GitHub (pinned to f3efcbfc9b)

Solutions

  1. Percent-encode the URI: replace spaces with %20 and any literal % with %25
  2. Fix the malformed URI syntax flagged by the hint (e.g. stray %, brackets)
  3. Use a plain relative file path instead of a partially-formed URI

Example fix

// before
"my file%.pkl"

// after
"my%20file%25.pkl"
Defensive patterns

Strategy: try-catch

Validate before calling

// validate the uri string before placing it in an import entry
function isValidUri(s: String): Boolean {
  try {
    new java.net.URI(if (s.contains(":")) s else "file://" + encodePath(s))
    true
  } catch (e: URISyntaxException) { false }
}

Try / catch

try {
  context = parseTestContext(...)
} catch (EvaluationException e) {
  if (e.getMessage().startsWith("invalidModuleUri")) {
    // e has a hint with the URISyntaxException reason; fix the uri string
  }
}

Prevention

When it happens

Trigger: An import entry value containing characters illegal in a URI (spaces, stray `%` not followed by hex digits, unmatched brackets, illegal control characters), parsed via `new URI(...)` or Path.toUri in handleImport.

Common situations: File paths with unencoded spaces or `%` characters (e.g. "my dir/file%.pkl"); pasted URLs with typos; Windows paths with mixed separators entering the wrong branch; interpolating unescaped values into a URI.

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

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