apple/pkl · error · CliException

Directory $dir does not contain a PklProject file.

Error message

Directory $dir does not contain a PklProject file.

What it means

This error is thrown by the `pkl project` command when one of the directories given on the command line (or the working directory) does not contain a file named PklProject. The command requires each target directory to be a Pkl project root, so before doing any work it resolves PKL_PROJECT_FILENAME in each directory and aborts with a CliException if the file does not exist. It is a precondition check on the user-supplied directory inputs.

Source

Thrown at pkl-cli/src/main/kotlin/org/pkl/cli/CliProjectCommand.kt:41

import org.pkl.commons.cli.CliException
import org.pkl.core.module.ProjectDependenciesManager.PKL_PROJECT_FILENAME

abstract class CliProjectCommand(cliOptions: CliBaseOptions, private val projectDirs: List<Path>) :
  CliCommand(cliOptions) {

  protected val normalizedProjectFiles: List<Path> by lazy {
    if (projectDirs.isEmpty()) {
      val projectFile =
        cliOptions.normalizedWorkingDir.getProjectFile(cliOptions.normalizedRootDir)
          ?: throw CliException(
            "No project visible to the working directory. Ensure there is a PklProject file in the workspace, or provide an explicit project directory as an argument."
          )
      return@lazy listOf(projectFile.normalize())
    }
    projectDirs.map(cliOptions.normalizedWorkingDir::resolve).map { dir ->
      val projectFile = dir.resolve(PKL_PROJECT_FILENAME)
      if (!Files.exists(projectFile)) {
        throw CliException("Directory $dir does not contain a PklProject file.")
      }
      projectFile.normalize()
    }
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

Verify the directory contains a file named exactly PklProject (case-sensitive) with `ls <dir>/PklProject`
Pass the directory that actually contains the PklProject file, not its parent or a sibling
Run `pkl project init <dir>` to create a new PklProject file if the directory should be a project
Check the current working directory if no explicit directory was given; the command resolves relative dirs against it

Example fix

// before
pkl project ./mypkg/src
// after
pkl project ./mypkg  # directory containing PklProject

Defensive patterns

Strategy: validation

Validate before calling

if not (dir / "PklProject").exists(): raise SystemExit(f"{dir} lacks PklProject; run `pkl project init {dir}`")

Prevention

Verify PklProject exists before invoking any `pkl project` subcommand
Note PklProject (no extension, exact case) is required
Point commands at the project root, not subdirectories

When it happens

Trigger: Running `pkl project <dir>` (or relying on the normalized working directory) where <dir> exists but contains no PklProject file; typos in the path passed with --project-dir style options; running the command from a directory that only contains sub-projects.

Common situations: Running `pkl project` in a repo root that only has PklProject files in subdirectories; misspelling the project directory; assuming a plain directory of .pkl files is a project; renaming or deleting the PklProject file during refactoring.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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