apple/pkl · error · PklException

unableToAccessPublishedPackage

unableToAccessPublishedPackage

Error message

ErrorMessages.create("unableToAccessPublishedPackage", pkg.name(), pkg.packageZipUrl(), statusCode)

What it means

Thrown when the pre-publish check tries to fetch the already-published package zip from the registry and receives an unexpected HTTP status code (anything other than 200 or 404). It indicates the registry is unreachable, misbehaving, or the package URL is wrong, so Pkl cannot determine whether the package was already published.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/project/ProjectPackager.java:243

      var metadataAndChecksum = packageResolver.getDependencyMetadataAndComputeChecksum(pkg.uri());
      var receivedChecksum = metadataAndChecksum.second.getSha256();
      if (!receivedChecksum.equals(computedChecksum)) {
        throw new PklException(
            ErrorMessages.create(
                "packageAlreadyPublishedWithDifferentContents",
                pkg.uri(),
                computedChecksum,
                receivedChecksum));
      }
    } catch (PackageLoadError e) {
      if (e.getMessageName().equals("badHttpStatusCode")) {
        var firstArg = e.getArguments()[0];
        assert firstArg != null;
        var statusCode = (int) firstArg;
        if (statusCode == 404) {
          return;
        } else {
          throw new PklException(
              ErrorMessages.create(
                  "unableToAccessPublishedPackage", pkg.name(), pkg.packageZipUrl(), statusCode));
        }
      }
      throw e;
    } catch (SecurityManagerException e) {
      throw new PklException(e.getMessage());
    }
  }

  private String createDependencyMetadataAndComputeChecksum(
      Project project, Package pkg, Path metadataFile, String zipFileChecksum) throws IOException {
    var dependencyMetadata = createDependencyMetadata(project, pkg, zipFileChecksum);
    try (var fos = newDigestOutputStream(Files.newOutputStream((metadataFile)))) {
      dependencyMetadata.writeTo(fos);
      return ByteArrayUtils.toHex(fos.getMessageDigest().digest());
    }
  }

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Check the reported HTTP status code against the registry: fix authentication (401/403) or retry later if it's a 5xx outage
2. Verify the `repositoryUrl`/registry configuration in PklProject points to the correct host
3. Test the package zip URL directly (curl) to confirm what the server returns

Example fix

// before (PklProject)
package { repositoryUrl = "https://example.wrong/host" }
// after
package { repositoryUrl = "https://registry.pkl-lang.org/package-annotation" }

// check the registry is reachable before packaging
curl -s -o /dev/null -w '%{http_code}' "$REPO_URL" | grep -q '^2' || echo 'registry unreachable'

try { packager.package(project) } catch (PklException e) { if (e.message.contains("unableToAccessPublishedPackage")) checkRegistryStatus(extractStatusCode(e)) else throw e }

When it happens

Trigger: During doPackage, the SecurityManager fetch of pkg.packageZipUrl() fails with a non-404 HTTP error status (e.g. 401, 403, 500, 502).

Common situations: Corporate proxy or firewall returning 403; registry outage returning 5xx; expired credentials for a private registry; typo'd repository URL in PklProject.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• errorConnectingToHost
• httpTooManyRedirects
• httpRedirectNoLocation
• ioErrorMakingHttpGet
• badHttpStatusCode

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