apple/pkl · error · VmException

cannotLoadProjectDepsJson

cannotLoadProjectDepsJson

Error message

cannotLoadProjectDepsJson

What it means

cannotLoadProjectDepsJson is thrown by ProjectDependenciesManager.getProjectDeps (projectDeps, resolvedDep, dep builtins) when the PklProject.deps.json file referenced by the project cannot be read or parsed as a source. It wraps the underlying IOException as the cause and surfaces the exception's message as a hint. It means the dependency lockfile exists at the deps URI but loading its bytes failed (I/O error, not a JSON syntax problem — that's invalidProjectDepsJson).

Source

Thrown at pkl-core/src/main/java/org/pkl/core/module/ProjectDependenciesManager.java:254

  public URI getProjectDepsFileUri() {
    return IoUtils.resolve(projectBaseUri, PKL_PROJECT_DEPS_FILENAME);
  }

  public URI getProjectFileUri() {
    return declaredDependencies.projectFileUri();
  }

  private ProjectDeps getProjectDeps() {
    synchronized (lock) {
      if (projectDeps == null) {
        var depsUri = getProjectDepsFileUri();
        var moduleKey = moduleResolver.resolve(depsUri);
        try {
          // treat PklProject.deps.json as a module read, rather than introduce a new API.
          var depsJson = moduleKey.resolve(securityManager).loadSource();
          projectDeps = ProjectDeps.parse(depsJson);
        } catch (IOException e) {
          throw new VmExceptionBuilder()
              .evalError("cannotLoadProjectDepsJson", depsUri)
              .withCause(e)
              .withHint(e.getMessage() != null ? e.getMessage() : ("Encountered error: " + e))
              .build();
        } catch (JsonParseException e) {
          throw new VmExceptionBuilder()
              .evalError("invalidProjectDepsJson", depsUri, e.getMessage())
              .build();
        } catch (SecurityManagerException e) {
          throw PklBugException.unreachableCode();
        }
      }
      return projectDeps;
    }
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Regenerate the deps file with `pkl project resolve` in the project root.
2. Check the hint/cause message for the exact I/O failure and fix that (permissions, missing file, path points at a directory).
3. Verify PklProject.deps.json exists and is a readable regular file next to PklProject.pkl.
4. Re-clone or restore the project directory from source control if the checkout is stale or corrupted.

Example fix

// before: deps file missing/stale
$ pkl eval mypkg/....pkl  # cannotLoadProjectDepsJson: file:///.../PklProject.deps.json
// after
$ pkl project resolve
$ pkl eval mypkg/....pkl

import java.nio.file.*;
Path deps = Path.of(projectDir).resolve("PklProject.deps.json");
if (!Files.isRegularFile(deps)) throw new IllegalStateException("Missing/unreadable " + deps + "; run `pkl project resolve`");
if (!Files.isReadable(deps)) throw new IllegalStateException("No read permission on " + deps);

When it happens

Trigger: Calling projectDeps, resolvedDep, or dep from Pkl code when moduleKey.resolve(securityManager).loadSource() on the PklProject.deps.json URI throws IOException — e.g. file deleted after resolution, permissions denied, or path is a directory.

Common situations: Running pkl commands in a project where PklProject.deps.json was removed or locked by another process (e.g. during `pkl project` resolution), stale read-only checkouts, CI caches where the deps file is a directory stub, or network-backed filesystems dropping the file mid-read.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• invalidProjectDepsJson
• projectDependenciesOutOfDateInProject
• unresolvedProjectDependency
• ioErrorWritingTestOutputFile
• ioErrorReadingTestOutputFile

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