apple/pkl · error · URISyntaxException

invalidSchemeInPackageUri

invalidSchemeInPackageUri

Error message

invalidSchemeInPackageUri

What it means

Thrown by the PackageUri constructor when a URI passed to it is opaque or uses a scheme other than 'package' or 'projectpackage'. Package URIs in Pkl must be hierarchical URIs with one of those two schemes; anything else is rejected at parse time.

Source

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

    try {
      return new PackageUri(baseUri);
    } catch (URISyntaxException e) {
      throw new IllegalArgumentException(e);
    }
  }

  public PackageUri(String baseUri) throws URISyntaxException {
    this(new URI(baseUri));
  }

  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"));
      }

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Prefix the URI with the correct scheme 'package://' (or 'projectpackage://'), e.g. package://example.com/foo@1.0.0
2. Fix the scheme spelling to exactly 'package' or 'projectpackage' (case-sensitive equals check)
3. If you have an opaque URI (no '//'), restructure it as scheme://authority/path
4. Verify you are not passing an https:// registry URL where a package: URI is required

Example fix

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

boolean hasValidPackageUriScheme(URI uri) {
  var scheme = uri.getScheme();
  return !uri.isOpaque() && ("package".equals(scheme) || "projectpackage".equals(scheme));
}

static boolean isPackageUri(URI uri) {
  return !uri.isOpaque() && ("package".equals(uri.getScheme()) || "projectpackage".equals(uri.getScheme()));
}

try {
  var pkg = new PackageUri(uri);
} catch (URISyntaxException e) {
  throw new IllegalArgumentException("Not a valid package URI (bad scheme): " + uri, e);
}

When it happens

Trigger: Calling new PackageUri(URI) or PackageUtils.parsePackageUriWithoutChecksums with a URI whose scheme is null, or is not exactly 'package' or 'projectpackage' (e.g. 'https://...', 'pkg://...', or a scheme-less relative path).

Common situations: Typos like 'pkg:' instead of 'package:'; hardcoding an https URL of a registry instead of the package: URI; passing a relative path from config where a package URI is expected; forgetting the scheme entirely.

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

• missingAuthorityInPackageUri
• missingPathInPackageUri
• invalidRelativePathInPackageUri
• missingVersionInPackageUri
• invalidPackageUriChecksum

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