{"record":{"id":"01f38e4f3a766c1b","repo":"apple/pkl","slug":"unexpectedpackageloaderror","errorCode":"unexpectedPackageLoadError","errorMessage":"ErrorMessages.create(\"unexpectedPackageLoadError\", project.getProjectFileUri(), e.getMessage())","messagePattern":"ErrorMessages\\.create\\(\"unexpectedPackageLoadError\", project\\.getProjectFileUri\\(\\), e\\.getMessage\\(\\)\\)","errorType":"error_code","errorClass":"PklException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/project/ProjectPackager.java","lineNumber":307,"sourceCode":"        var resolved = projectDependenciesManager.getResolvedDependency(packageUri);\n        if (resolved instanceof LocalDependency) {\n          var packageResult = doPackage(localProject);\n          ret.put(\n              entry.getKey(),\n              new RemoteDependency(\n                  packageUri.toExternalPackageUri(),\n                  new Checksums(packageResult.metadataChecksum())));\n        } else {\n          var remoteDep = (RemoteDependency) resolved;\n          ret.put(\n              entry.getKey(),\n              new RemoteDependency(\n                  remoteDep.getPackageUri().toExternalPackageUri(), remoteDep.getChecksums()));\n        }\n      }\n      return ret;\n    } catch (PackageLoadError e) {\n      throw new PklException(\n          ErrorMessages.create(\n              \"unexpectedPackageLoadError\", project.getProjectFileUri(), e.getMessage()),\n          e);\n    }\n  }\n\n  private DependencyMetadata createDependencyMetadata(\n      Project project, Package pkg, String packageZipChecksum) throws IOException {\n    return new DependencyMetadata(\n        pkg.name(),\n        pkg.uri(),\n        pkg.version(),\n        pkg.packageZipUrl(),\n        new Checksums(packageZipChecksum),\n        buildDependencies(project),\n        pkg.sourceCodeUrlScheme(),\n        pkg.sourceCode(),\n        pkg.documentation(),","sourceCodeStart":289,"sourceCodeEnd":325,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/project/ProjectPackager.java#L289-L325","documentation":"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.","triggerScenarios":"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.","commonSituations":"A dependency listed in PklProject was never fetched/updated; stale lockfile-style metadata after registry changes; corrupted local package cache under ~/.pkl.","solutions":["Run `pkl project resolve` to refresh and fetch all declared dependencies","Clear the stale cache entry for the failing package (rm -rf ~/.pkl/cache/repo/...) and re-resolve","Check the underlying PackageLoadError message for the exact dependency URI and fix its coordinates in PklProject"],"exampleFix":"// terminal\npkl project resolve   // before packaging\ngit add PklProjectDependencies.json && pkl project package","handlingStrategy":"validation","validationCode":"// resolve dependencies before packaging\npkl project resolve --no-transitive || echo 'dependency resolution failed'","typeGuard":null,"tryCatchPattern":"try { packager.package(project) } catch (PklException e) { if (e.message.contains(\"unexpectedPackageLoadError\")) { runResolveAndRetry(); } else throw e; }","preventionTips":["Always run `pkl project resolve` after changing dependencies in PklProject","Commit PklProjectDependencies.json so CI has consistent metadata","Clear corrupted ~/.pkl cache entries rather than ignoring errors"],"tags":["dependencies","packaging"],"backgroundTag":"missing-dependency","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}