apple/pkl · error · PklException

unexpectedPackageLoadError

unexpectedPackageLoadError

Error message

ErrorMessages.create("unexpectedPackageLoadError", project.getProjectFileUri(), e.getMessage())

What it means

Wraps a PackageLoadError encountered while resolving the project's dependencies into metadata for packaging. Pkl considers failing to load a declared dependency at this stage unexpected (it should have been resolvable), so it re-raises with the project file URI and the underlying message.

Solutions

1. Run `pkl project resolve` to refresh and fetch all declared dependencies
2. Clear the stale cache entry for the failing package (rm -rf ~/.pkl/cache/repo/...) and re-resolve
3. Check the underlying PackageLoadError message for the exact dependency URI and fix its coordinates in PklProject

Example fix

// terminal
pkl project resolve   // before packaging
git add PklProjectDependencies.json && pkl project package

// resolve dependencies before packaging
pkl project resolve --no-transitive || echo 'dependency resolution failed'

try { packager.package(project) } catch (PklException e) { if (e.message.contains("unexpectedPackageLoadError")) { runResolveAndRetry(); } else throw e; }

When it happens

Trigger: buildDependencies, called from createDependencyMetadata during `pkl project package`, resolves the project's local/remote dependencies and one raises PackageLoadError — e.g. a declared remote dependency cannot be found in the local cache or the repository.

Common situations: A dependency listed in PklProject was never fetched/updated; stale lockfile-style metadata after registry changes; corrupted local package cache under ~/.pkl.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• missingProjectInPackageCommand
• cannotFindDependencyInProject
• cannotInstallPackageWithNoCache
• cannotResolveDependencyNoProject
• cannotResolveDependencyWithoutHierarchicalUris

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

Appendix: source

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

        var resolved = projectDependenciesManager.getResolvedDependency(packageUri);
        if (resolved instanceof LocalDependency) {
          var packageResult = doPackage(localProject);
          ret.put(
              entry.getKey(),
              new RemoteDependency(
                  packageUri.toExternalPackageUri(),
                  new Checksums(packageResult.metadataChecksum())));
        } else {
          var remoteDep = (RemoteDependency) resolved;
          ret.put(
              entry.getKey(),
              new RemoteDependency(
                  remoteDep.getPackageUri().toExternalPackageUri(), remoteDep.getChecksums()));
        }
      }
      return ret;
    } catch (PackageLoadError e) {
      throw new PklException(
          ErrorMessages.create(
              "unexpectedPackageLoadError", project.getProjectFileUri(), e.getMessage()),
          e);
    }
  }

  private DependencyMetadata createDependencyMetadata(
      Project project, Package pkg, String packageZipChecksum) throws IOException {
    return new DependencyMetadata(
        pkg.name(),
        pkg.uri(),
        pkg.version(),
        pkg.packageZipUrl(),
        new Checksums(packageZipChecksum),
        buildDependencies(project),
        pkg.sourceCodeUrlScheme(),
        pkg.sourceCode(),
        pkg.documentation(),

View on GitHub (pinned to f3efcbfc9b)