apple/pkl · error · URISyntaxException

invalidPackageUriChecksum

invalidPackageUriChecksum

Error message

ErrorMessages.create("invalidPackageUriChecksum", checksumPart)

What it means

Thrown by PackageUri.parseChecksumPart when the '::'-delimited checksum component is not exactly 'algorithm:checksum' (a single colon splitting into two parts). The optional checksums suffix of a package URI must look like '::sha256:abc123...'.

Source

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

              uri.getQuery(),
              uri.getFragment()));
    } catch (URISyntaxException e) {
      throw PklBugException.unreachableCode();
    }
  }

  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

Format the checksum suffix as '::sha256:<hex-checksum>' exactly
Verify the URI was not truncated or mangled by copy/paste or string processing
Remove the checksum component entirely if you don't need checksum verification

Example fix

// before
var uri = "package://example.com/my-pkg@1.2.3::sha256";
// after
var uri = "package://example.com/my-pkg@1.2.3::sha256:4f3c...";

Defensive patterns

Strategy: validation

Validate before calling

boolean hasValidChecksumPart(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 && !pieces[0].isEmpty() && !pieces[1].isEmpty();
}

Try / catch

try {
  var pkg = new PackageUri(URI.create(uriStr));
} catch (URISyntaxException e) {
  throw new IllegalArgumentException("Malformed checksum component (want '::sha256:<hex>'): " + uriStr, e);
}

Prevention

Format checksum suffixes exactly as '::sha256:<hex>'
Avoid hand-editing checksummed URIs; regenerate them with tooling
Watch for string processing that adds/removes colons

When it happens

Trigger: Parsing a package URI whose checksum suffix has the wrong shape: extra colons, missing the algorithm, or empty checksum, e.g. '::sha256' or ':::abc' or '::abc:def:ghi'.

Common situations: Hand-editing a checksummed dependency URI; truncating or concatenating checksum strings; copying a URI with formatting artifacts that add or remove colons.

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

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