apple/pkl · error

invalidModuleUri

invalidModuleUri

Error message

invalidModuleUri ${importUri}

What it means

An import URI string failed to parse as a URI (`IoUtils.toUri` raised URISyntaxException) while resolving an `import` statement. The error carries the offending import string and a hint from the parser about why the URI is malformed.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/builder/AstBuilder.java:3228

        .withMemberName(symbolTable.getCurrentScope().getQualifiedName());
  }

  private SymbolTable.@Nullable Scope getParentLexicalScope() {
    var parent = symbolTable.getCurrentScope().getLexicalScope().getParent();
    if (parent != null) return parent.getLexicalScope();
    return null;
  }

  private org.pkl.core.runtime.Identifier toIdentifier(String text) {
    return org.pkl.core.runtime.Identifier.get(text);
  }

  private URI resolveImport(String importUri, StringConstant ctx) {
    URI parsedUri;
    try {
      parsedUri = IoUtils.toUri(importUri);
    } catch (URISyntaxException e) {
      throw exceptionBuilder()
          .evalError("invalidModuleUri", importUri)
          .withHint(e.getReason())
          .withSourceSection(createSourceSection(ctx))
          .build();
    }
    URI resolvedUri;
    var context = VmContext.get(null);
    try {
      resolvedUri = IoUtils.resolve(context.getSecurityManager(), moduleKey, parsedUri);
    } catch (FileNotFoundException e) {

      var exceptionBuilder =
          exceptionBuilder()
              .evalError("cannotFindModule", importUri)
              .withSourceSection(createSourceSection(ctx));
      var path = parsedUri.getPath();
      if (path != null && path.contains("\\")) {
        exceptionBuilder.withHint(

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Fix the import string so it is a valid URI (read the parser hint attached to the error)
2. Percent-encode spaces and special characters
3. Use forward slashes and a proper `file:///` scheme for absolute file imports
4. Use a relative path only when it is a valid URI reference

Example fix

// before
import "my modules/config.pkl"
// after
import "my%20modules/config.pkl"

function isValidImportUri(s) {
  try { new URL(s, 'file:///'); return true } catch { return false }
}

When it happens

Trigger: An `import "..."` statement whose string is not a valid URI — illegal characters, spaces, unescaped `|`/`#`, malformed percent-encoding, or a scheme-less relative path containing URI-invalid characters.

Common situations: File paths with spaces pasted into imports; Windows `C:\...` paths without `file:///`; special characters in module names not URL-encoded.

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

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

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