apple/pkl · error · PackageLoadError

invalidDependencyMetadata

invalidDependencyMetadata

Error message

invalidDependencyMetadata

What it means

Pkl failed to parse the dependency metadata file (DependencyMetadata.json) fetched from a package's remote repository as JSON. PackageLoadError invalidDependencyMetadata is thrown by readDependencyMetadataAndComputeChecksum when Jackson raises a JsonParseException, wrapping the underlying parser message. It means the bytes at the metadata request URI are not well-formed JSON.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/packages/PackageResolvers.java:118

    @Override
    public Pair<DependencyMetadata, Checksums> getDependencyMetadataAndComputeChecksum(
        PackageUri packageUri) throws IOException, SecurityManagerException {
      var requestUri = packageUri.getMetadataRequestUri();
      var inputStream = openExternalUri(requestUri);
      return readDependencyMetadataAndComputeChecksum(packageUri, inputStream);
    }

    protected Pair<DependencyMetadata, Checksums> readDependencyMetadataAndComputeChecksum(
        PackageUri packageUri, InputStream inputStream) throws IOException {
      try (var in = newDigestInputStream(inputStream)) {
        var bytes = in.readAllBytes();
        var dependencyMetadata =
            DependencyMetadata.parse(new String(bytes, StandardCharsets.UTF_8));
        var checksums = new Checksums(ByteArrayUtils.toHex(in.getMessageDigest().digest()));
        return Pair.of(dependencyMetadata, checksums);
      } catch (JsonParseException e) {
        throw new PackageLoadError(
            e,
            "invalidDependencyMetadata",
            packageUri.getDisplayName(),
            packageUri.getMetadataRequestUri(),
            e.getMessage());
      }
    }

    @Override
    public List<PathElement> listElements(PackageAssetUri uri, @Nullable Checksums checksums)
        throws IOException, SecurityManagerException {
      checkNotClosed();
      return doListElements(uri, checksums);
    }

    @Override
    public boolean hasElement(PackageAssetUri uri, @Nullable Checksums checksums)
        throws IOException, SecurityManagerException {

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Inspect the URL from the error message (packageUri metadata request URI) in a browser or curl and check whether it returns valid JSON.
2. Check for a proxy/firewall intercepting HTTPS requests and returning HTML; bypass or configure the proxy correctly.
3. Retry later if the package repository is temporarily broken, or use a different version of the package.
4. If you host the repository, re-upload or fix the DependencyMetadata.json file.

Example fix

// before: intercepted response parsed as JSON
DependencyMetadata.parse(new String(bytes, StandardCharsets.UTF_8)); // JsonParseException
// after: verify the endpoint returns JSON first (shell)
// curl -fsSL https://example.com/pkl/.../DependencyMetadata.json | jq .

// shell: verify the metadata endpoint serves JSON before running pkl
// curl -fsSL "$URL" | jq -e . >/dev/null && echo ok || echo 'metadata is not valid JSON'

When it happens

Trigger: Resolving a remote Pkl package whose DependencyMetadata.json is corrupt, truncated, HTML (e.g. a captive portal or error page returned with 200), or served from a wrong/non-repository URL.

Common situations: A proxy or corporate firewall intercepts the request and returns an HTML login page; a self-hosted package repository misconfigures the metadata path; the package registry is temporarily broken or the cached/uploaded metadata file was corrupted.

Understand the failure class

Background: "Invalid JSON response" and "Failed to parse response" errors: when an API answers 200 but the body isn't the JSON your library expected — this error's family across 28 libraries.

Related errors

• ioErrorMakingHttpGet
• Values of type `Duration` cannot be rendered as JSON. Value:
• Values of type `DataSize` cannot be rendered as JSON. Value:
• Values of type `Bytes` cannot be rendered as JSON. Value: %s
• Maps containing non-String keys cannot be rendered as JSON.

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