apple/pkl · error · CliException

No project visible to the working directory. Ensure there is

Error message

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.

What it means

All `pkl project` subcommands require a visible PklProject file: either explicit project directories were given, or the working directory (searched up to the root dir) contains a PklProject. CliProjectCommand's `normalizedProjectFiles` lazy property throws this when no project can be located.

Source

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

 */
package org.pkl.cli

import java.nio.file.Files
import java.nio.file.Path
import org.pkl.commons.cli.CliBaseOptions
import org.pkl.commons.cli.CliBaseOptions.Companion.getProjectFile
import org.pkl.commons.cli.CliCommand
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

1. Run the command from inside the project directory (where PklProject lives).
2. Pass the project directory explicitly: `pkl project package path/to/project`.
3. Create a PklProject file if the project genuinely lacks one (`pkl project init`).

Example fix

# before (run from repo root without PklProject)
pkl project package
# after
cd services/api && pkl project package
# or
pkl project package services/api

// before invoking any pkl project subcommand
val cwd = Path.of(".").toAbsolutePath()
val hasProject = generateSequence(cwd) { it.parent }.any { Files.exists(it.resolve("PklProject")) }
check(hasProject) { "no PklProject visible; pass a project dir explicitly" }

try {
  pklCli.runProject(args)
} catch (e: CliException) {
  if (e.message?.startsWith("No project visible") == true) {
    exec("pkl project ... $explicitProjectDir")
  } else throw e
}

When it happens

Trigger: Running `pkl project ...` (e.g. `pkl project package`) from a directory without a PklProject in it or any ancestor up to normalizedRootDir, and without passing a project directory argument.

Common situations: Running the command from a subdirectory whose parents were pruned of PklProject; running from a temp dir or repo root that has no PklProject at top level; forgetting the directory argument after a workspace restructure.

Understand the failure class

Background: "Config file not found": what it means and how to fix it in docker-sync, Maven, Vagrant, Turborepo and other tools — this error's family across 60 libraries.

Related errors

• Directory $dir does not contain a PklProject file.
• +e.getMessage()
• cannotResolveDependencyNoProject
• cannotFindDependencyInProject
• Output path `$outputDir` exists and is not a directory.

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