apple/pkl · error · CliException

Could not find a doc-package-info.pkl for module $uri

Error message

Could not find a doc-package-info.pkl for module $uri

What it means

Every regular module passed to pkl-doc must fall under the parent path of some `doc-package-info.pkl` module, since package metadata scopes documentation. When a module's path does not start with any known doc-package-info parent directory, generation aborts with this error naming the offending module URI.

Solutions

Move the module under the directory of an existing `doc-package-info.pkl`, or
Add a `doc-package-info.pkl` in the module's parent directory and pass it in sourceModules
Verify the module URI/path in the error matches the intended package root

Example fix

// before
pkl-doc docsite-info.pkl pkg/doc-package-info.pkl other/Stray.pkl
// after (move Stray.pkl under pkg/ or add its own doc-package-info.pkl)
pkl-doc docsite-info.pkl pkg/doc-package-info.pkl pkg/Stray.pkl

Defensive patterns

Strategy: validation

Validate before calling

val pkgRoots = docPackageInfoUris.map { it.toPath().parent }
val strays = regularModuleUris.filter { uri -> pkgRoots.none { uri.toPath().startsWith(it) } }
require(strays.isEmpty()) { "Modules outside any doc-package-info scope: $strays" }

Try / catch

try { pklDoc(args) } catch (e: CliException) { if (e.message?.startsWith("Could not find a doc-package-info.pkl") == true) { /* move module or add package-info for its dir */ } else throw e }

Prevention

Keep all documented modules under the package-info directory
Add a doc-package-info.pkl for each independent module root
Verify paths resolve relative to the same base directory

When it happens

Trigger: Passing a module URI whose path is outside the directory tree of every `doc-package-info.pkl` in `sourceModules`, e.g. documenting `shared/Util.pkl` when the package-info lives in `packages/mypkg/`.

Common situations: Module placed outside the package root by mistake; mixing modules from multiple directories with only one doc-package-info.pkl; typos or differing relative-path bases in the CLI arguments.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at pkl-doc/src/main/kotlin/org/pkl/doc/CliDocGenerator.kt:263

              DocsiteInfo.fromPkl(module).apply {
                evaluator.collectImportedModules(overviewImports)
              }
            }
          }

        for (uri in packageInfoModuleUris) {
          val module = evaluator.evaluate(ModuleSource.uri(uri))
          val docPackageInfo =
            DocPackageInfo.fromPkl(module).apply {
              evaluator.collectImportedModules(overviewImports)
            }
          schemasByDocPackageInfoAndPath[docPackageInfo to uri.toPath().parent] = mutableSetOf()
        }

        for (uri in regularModuleUris) {
          val entry =
            schemasByDocPackageInfoAndPath.keys.find { uri.toPath().startsWith(it.second) }
              ?: throw CliException("Could not find a doc-package-info.pkl for module $uri")
          val schema =
            evaluator.evaluateSchema(ModuleSource.uri(uri)).apply {
              evaluator.collectImportedModules(imports)
            }
          schemasByDocPackageInfoAndPath[entry]!!.add(schema)
        }

        // doc generator resolves `pkl.base` even if not imported explicitly
        val pklBaseUri = URI("pkl:base")
        importedModules[pklBaseUri] = evaluator.evaluateSchema(ModuleSource.uri(pklBaseUri))
      }
    } finally {
      Closeables.closeQuietly(builder.moduleKeyFactories)
      Closeables.closeQuietly(builder.resourceReaders)
    }

    val versions = mutableMapOf<String, Version>()
    val versionComparator =

View on GitHub (pinned to f3efcbfc9b)