apple/pkl · error · IllegalArgumentException

invalidModuleUriMissingSlash

invalidModuleUriMissingSlash

Error message

invalidModuleUriMissingSlash

What it means

ModulePath module keys require URIs with a path component. If uri.getPath() returns null (an opaque URI such as foo:bar with no '/' path), the ModulePath constructor throws IllegalArgumentException with error invalidModuleUriMissingSlash, indicating the module URI is missing its '/' path part.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/module/ModuleKeys.java:384

    @Override
    public boolean isLocal() {
      return true;
    }

    @Override
    public boolean hasHierarchicalUris() {
      return true;
    }
  }

  private static final class ModulePath implements ModuleKey {
    final URI uri;
    final ModulePathResolver resolver;

    ModulePath(URI uri, ModulePathResolver resolver) {
      if (uri.getPath() == null) {
        throw new IllegalArgumentException(
            ErrorMessages.create("invalidModuleUriMissingSlash", uri, "modulepath"));
      }

      this.uri = uri;
      this.resolver = resolver;
    }

    @Override
    public URI getUri() {
      return uri;
    }

    @Override
    public boolean hasHierarchicalUris() {
      return true;
    }

    @Override

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Add a leading slash / path component to the URI (e.g. modulepath:/my/module.pkl)
2. Ensure programmatically constructed URIs include a path (new URI(scheme, host, path...))
3. Validate URIs before passing them into Pkl module resolution

Example fix

// before
var uri = URI.create("modulepath:foo.pkl"); // opaque, no path -> IllegalArgumentException
// after
var uri = URI.create("modulepath:/foo.pkl");

requireNonNull(uri.getPath(), "module URI must contain a '/' path");

null

null

When it happens

Trigger: Constructing a ModulePath key (directly or via ModuleKeys.forUri-style resolution of a modulepath: or classpath-style URI) with an URI that has no path component.

Common situations: Writing 'modulepath:my/pkg' instead of 'modulepath:/my/pkg'; programmatically building URIs without the leading slash; copy-pasted opaque URIs from other tooling.

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

• Failed to convert `pkl.base#String` to `java.net.URI`.
• invalidModuleUriMissingSlash
• invalidModuleUri
• invalidOpaqueFileUri
• `%s` could not be parsed as a semantic version number.

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