apple/pkl · error · CliException

`sourceModules` must contain at least one module to generate

Error message

`sourceModules` must contain at least one module to generate documentation for.

What it means

pkl-doc throws when there is nothing to document: `sourceModules` contains no regular modules and no package URIs were given. The generator has no modules to produce documentation for, so it fails fast before building the evaluator.

Source

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

        else -> regularModuleUris.add(moduleUri)
      }
    }

    if (docsiteInfoModuleUris.size > 1) {
      throw CliException(
        "`sourceModules` contains multiple modules named `docsite-info.pkl`:\n" +
          docsiteInfoModuleUris.joinToString("\n")
      )
    }

    if (packageInfoModuleUris.isEmpty() && packageUris.isEmpty()) {
      throw CliException(
        "`sourceModules` must contain at least one module named `doc-package-info.pkl`, or an argument must be a package URI."
      )
    }

    if (regularModuleUris.isEmpty() && packageUris.isEmpty()) {
      throw CliException(
        "`sourceModules` must contain at least one module to generate documentation for."
      )
    }

    val builder = evaluatorBuilder()
    var docsiteInfo: DocsiteInfo
    val schemasByDocPackageInfoAndPath =
      mutableMapOf<Pair<DocPackageInfo, Path>, MutableSet<ModuleSchema>>()
    val schemasByDocPackageInfo = mutableMapOf<DocPackageInfo, Set<ModuleSchema>>()
    // Evaluate module imports eagerly, which is cheap if docs are also generated for most imported
    // modules.
    // Alternatively, imports could be evaluated lazily,
    // at the expense of interleaving schema/module evaluation and Pkldoc generation.
    val importedModules: MutableMap<URI, ModuleSchema> = mutableMapOf()

    try {
      fun Evaluator.collectImportedModules(imports: Map<String, URI>) {
        for ((_, uri) in imports) {

View on GitHub (pinned to f3efcbfc9b)

Solutions

  1. Add at least one regular module or package URI argument to the command
  2. Verify any glob/script variable expanding to module paths is non-empty
  3. Check the command in CI logs — the arguments may have been dropped by quoting

Example fix

// before
pkl-doc docsite-info.pkl
// after
pkl-doc docsite-info.pkl com/example/pkg/Module.pkl
Defensive patterns

Strategy: validation

Validate before calling

val docTargets = sourceModules.filter { it.fileName !in setOf("docsite-info.pkl", "doc-package-info.pkl") } + packageUris
require(docTargets.isNotEmpty()) { "No modules or packages to document" }

Try / catch

try { pklDoc(args) } catch (e: CliException) { if (e.message?.contains("at least one module to generate documentation") == true) { /* fix empty arg list */ } else throw e }

Prevention

When it happens

Trigger: Running `pkl-doc` with only a `docsite-info.pkl` (or doc-package-info) module as sourceModules and zero regular modules and zero package URI arguments.

Common situations: Empty or misconfigured CI command; glob pattern in a script matched no files so only the info module remained; intending to pass packages but forgetting the package URI arguments.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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