apple/pkl · error · URISyntaxException

unknownChecksumAlgorithm

unknownChecksumAlgorithm

Error message

ErrorMessages.create("unknownChecksumAlgorithm", algorithm)

What it means

Validation in PackageUri.parseChecksumPart: the checksum segment of a package URI may only use the sha256 algorithm; any other algorithm name (the first part before ':') is rejected with URISyntaxException. The input at fault is a checksum part like `md5:...` in the package URI's checksum component.

Source

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

  public String getPathWithoutVersion() {
    return pathWithoutVersion;
  }

  public @Nullable Checksums getChecksums() {
    return checksums;
  }

  private Checksums parseChecksumPart(String checksumPart) throws URISyntaxException {
    var parts = checksumPart.split(":");
    if (parts.length != 2) {
      throw new URISyntaxException(
          uri.toString(), ErrorMessages.create("invalidPackageUriChecksum", checksumPart));
    }
    var algorithm = parts[0];
    var checksum = parts[1];
    if (!algorithm.equals("sha256")) {
      throw new URISyntaxException(
          uri.toString(), ErrorMessages.create("unknownChecksumAlgorithm", algorithm));
    }
    return new Checksums(checksum);
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Use a sha256 checksum in the package URI: `sha256:<hex>`.
2. Drop the checksum component if no sha256 digest is available.

Example fix

// before
var uri = "package://example.com/my-pkg@1.2.3::sha512:abc...";
// after
var uri = "package://example.com/my-pkg@1.2.3::sha256:def658...";

boolean usesSha256(String uriStr) {
  int idx = uriStr.indexOf("::");
  if (idx == -1) return true;
  var part = uriStr.substring(idx + 2);
  String[] pieces = part.split(":");
  return pieces.length == 2 && "sha256".equals(pieces[0]);
}

try {
  var pkg = new PackageUri(URI.create(uriStr));
} catch (URISyntaxException e) {
  throw new IllegalArgumentException("Only sha256 checksums are supported: " + uriStr, e);
}

When it happens

Trigger: A package URI checksum suffix uses another algorithm name, e.g. '::sha512:abc...' or '::md5:abc...' — the equals("sha256") check fails.

Common situations: Writing a URI using a different hash algorithm than the tooling produced; hand-crafting checksummed URIs; migrating from tools that default to sha512/md5.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

• invalidPackageUriChecksum
• unexpectedChecksumInPackageUri
• invalidPackageZipChecksum
• invalidPackageMetadataChecksum
• invalidSchemeInPackageUri

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