apple/pkl · error · URISyntaxException

missingPathInPackageUri

missingPathInPackageUri

Error message

missingPathInPackageUri

What it means

Validation in the PackageUri(URI) constructor: the URI is opaque (no '/' after the scheme, e.g. `package:foo`), but package URIs must be hierarchical so the path can carry name/version/checksum parts. Input at fault: an opaque URI passed where a hierarchical `package://...` URI is required.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/packages/PackageUri.java:61

  public PackageUri(URI uri) throws URISyntaxException {
    if (uri.isOpaque()) {
      throw new URISyntaxException(
          uri.toString(), ErrorMessages.create("invalidModuleUriMissingSlash", uri, "package"));
    }
    var scheme = uri.getScheme();
    if (scheme == null || !(scheme.equals("package") || scheme.equals("projectpackage"))) {
      throw new URISyntaxException(
          uri.toString(), ErrorMessages.create("invalidSchemeInPackageUri", scheme));
    }
    var authority = uri.getAuthority();
    if (authority == null || authority.isEmpty()) {
      throw new URISyntaxException(
          uri.toString(), ErrorMessages.create("missingAuthorityInPackageUri", uri));
    }
    var path = uri.getPath();
    if (path == null || path.isEmpty()) {
      throw new URISyntaxException(
          uri.toString(), ErrorMessages.create("missingPathInPackageUri", uri));
    }
    // reject `..` segments, percent-encoded or not
    for (var segment : path.split("/", -1)) {
      if (segment.equals("..")) {
        throw new URISyntaxException(
            uri.toString(), ErrorMessages.create("invalidRelativePathInPackageUri"));
      }
    }
    var versionIdx = path.lastIndexOf('@');
    if (versionIdx == -1) {
      throw new URISyntaxException(
          uri.toString(), ErrorMessages.create("missingVersionInPackageUri", path));
    }
    this.uri = IoUtils.stripFragment(uri);
    this.pathWithoutVersion = path.substring(0, versionIdx);
    var checksumIdx = path.indexOf("::");
    var versionPart = path.substring(versionIdx + 1);

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Use the hierarchical form `package://<authority>/<path>` including the module path.
2. Obtain package URIs from the resolver or a valid package descriptor rather than constructing them by hand.

Example fix

// before
var uri = URI.create("package://example.com");
var pkg = new PackageUri(uri);
// after
var uri = URI.create("package://example.com/my-pkg@1.2.3");
var pkg = new PackageUri(uri);

boolean hasPath(URI uri) {
  var p = uri.getPath();
  return p != null && !p.isEmpty();
}

static boolean hasPackagePath(URI uri) {
  return uri.getPath() != null && !uri.getPath().isEmpty();
}

try {
  var pkg = new PackageUri(uri);
} catch (URISyntaxException e) {
  throw new IllegalArgumentException("Package URI missing path: " + uri, e);
}

When it happens

Trigger: new PackageUri(uri) with a pathless URI such as 'package://example.com' or 'package://example.com/' (getPath() null or empty).

Common situations: Copying only the registry base URL as a dependency; programmatically building a URI and forgetting to append the package name/version path; string concatenation bugs that drop the path segment.

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

• invalidSchemeInPackageUri
• missingAuthorityInPackageUri
• invalidRelativePathInPackageUri
• missingVersionInPackageUri
• Failed to convert `pkl.base#String` to `java.nio.file.Path`.

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