apple/pkl · error · URISyntaxException

missingVersionInPackageUri

missingVersionInPackageUri

Error message

missingVersionInPackageUri

What it means

Validation in the PackageUri(URI) constructor: after the authority check, the URI's path is null or empty, meaning the package URI carries no path segment. Package URIs must include a path holding the package coordinates; the input at fault is a `package://authority` URI with nothing after the authority.

Source

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

    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);
    if (checksumIdx > versionIdx) {
      var checksumPart = path.substring(checksumIdx + 2);
      versionPart = path.substring(versionIdx + 1, checksumIdx);
      this.checksums = parseChecksumPart(checksumPart);
    }
    try {
      this.version = Version.parse(versionPart);
    } catch (IllegalArgumentException e) {
      throw new URISyntaxException(uri.toString(), e.getMessage());
    }
  }

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Append the package path (name, version and optional checksum parts) after the authority.
2. Use a Package URI produced by the package manager instead of a hand-built URI.

Example fix

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

boolean hasVersion(String packageUriPath) {
  return packageUriPath != null && packageUriPath.lastIndexOf('@') != -1;
}

static boolean isVersionedPackageUri(String uriStr) {
  return uriStr != null && uriStr.lastIndexOf('@') != -1;
}

try {
  var pkg = new PackageUri(URI.create(uriStr));
} catch (URISyntaxException e) {
  throw new IllegalArgumentException("Package URI must include '@<version>': " + uriStr, e);
}

When it happens

Trigger: new PackageUri(uri) or parsePackageUriWithoutChecksums with a path like '/my-pkg' lacking '@1.2.3'; versionIdx = path.lastIndexOf('@') returns -1.

Common situations: Referencing a package without pinning a version; stripping the '@version' while transforming URIs; older dependency declarations written before version pinning became required.

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
• missingPathInPackageUri
• invalidRelativePathInPackageUri
• missingVersionInPackageUri

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