apple/pkl · error · URISyntaxException

unexpectedChecksumInPackageUri

unexpectedChecksumInPackageUri

Error message

ErrorMessages.create("unexpectedChecksumInPackageUri")

What it means

Thrown by PackageUtils.checkHasNoChecksumComponent when a parsed PackageUri still carries a checksums component. parsePackageUriWithoutChecksums is only for plain URIs; checksummed URIs (containing '::sha256:...') must go through the checksum-aware path.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/packages/PackageUtils.java:38

import org.pkl.core.util.json.Json.FormatException;
import org.pkl.core.util.json.Json.JsonParseException;

public final class PackageUtils {
  private PackageUtils() {}

  public static PackageUri parsePackageUriWithoutChecksums(Object obj)
      throws JsonParseException, URISyntaxException {
    if (!(obj instanceof String string)) {
      throw new FormatException("string", obj.getClass());
    }
    var packageUri = new PackageUri(string);
    checkHasNoChecksumComponent(packageUri);
    return packageUri;
  }

  public static void checkHasNoChecksumComponent(PackageUri packageUri) throws URISyntaxException {
    if (packageUri.getChecksums() != null) {
      throw new URISyntaxException(
          packageUri.toString(), ErrorMessages.create("unexpectedChecksumInPackageUri"));
    }
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Strip the '::...' checksum suffix from the URI before parsing
2. Use the checksum-aware parsing API instead of parsePackageUriWithoutChecksums
3. Regenerate the dependency URI without checksums if your pipeline cannot verify them

Example fix

// before
var pkg = PackageUtils.parsePackageUriWithoutChecksums(
    "package://example.com/my-pkg@1.2.3::sha256:abc");
// after
var pkg = PackageUtils.parsePackageUriWithoutChecksums(
    "package://example.com/my-pkg@1.2.3");

boolean hasNoChecksums(String uriStr) {
  return !uriStr.contains("::");
}

var pkgUri = new PackageUri(URI.create(uriStr));
if (pkgUri.getChecksums() != null) {
  throw new IllegalArgumentException("Unexpected checksum component in: " + uriStr);
}

When it happens

Trigger: Calling parsePackageUriWithoutChecksums on a URI string like 'package://example.com/my-pkg@1.2.3::sha256:abc' — getChecksums() is non-null so the check throws.

Common situations: Mixing checksummed and unchecksummed dependency URIs in the same config; upgrading packages that gained checksums while code still uses the no-checksum parser; copy/pasting URIs that include the '::sha256:...' suffix.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• invalidPackageUriChecksum
• unknownChecksumAlgorithm
• invalidPackageZipChecksum
• invalidPackageMetadataChecksum
• invalidSchemeInPackageUri

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