apple/pkl · error · CliException

`sourceModules` must contain at least one module named `doc-

Error message

`sourceModules` must contain at least one module named `doc-package-info.pkl`, or an argument must be a package URI.

What it means

pkl-doc requires either a module named `doc-package-info.pkl` among the `sourceModules`, or at least one argument that is a package URI, because package documentation metadata is what tells the generator what to document and how. Without either, there is no package context to generate docs for.

Source

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

          try {
            packageUris.add(PackageUri(moduleUri))
          } catch (e: URISyntaxException) {
            throw CliException(e.message!!)
          }
        }
        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,

View on GitHub (pinned to f3efcbfc9b)

Solutions

  1. Add a `doc-package-info.pkl` module to the `sourceModules` arguments, or
  2. Pass a package URI (e.g. `package://example.com/my/pkg@1.0.0`) as an argument
  3. Rename/verify the package-info module is exactly named `doc-package-info.pkl`

Example fix

// before
pkl-doc mypkg/Module.pkl
// after
pkl-doc mypkg/doc-package-info.pkl
Defensive patterns

Strategy: validation

Validate before calling

val hasPkgInfo = sourceModules.any { it.fileName == "doc-package-info.pkl" }
val hasPkgUri = args.any { it.startsWith("package://") }
require(hasPkgInfo || hasPkgUri) { "Need a doc-package-info.pkl module or a package URI" }

Try / catch

try { pklDoc(args) } catch (e: CliException) { if (e.message?.contains("doc-package-info.pkl") == true) { /* add package-info module */ } else throw e }

Prevention

When it happens

Trigger: Running `pkl-doc` where all `sourceModules` are regular modules (none named `doc-package-info.pkl`) and none of the arguments are package URIs (e.g. `package://...`).

Common situations: Documenting standalone modules without a doc-package-info.pkl; forgetting to include the package-info module when migrating from plain module docs; typo in the module file name (e.g. `docPackageInfo.pkl`).

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/dc7c2b0387e7b280. Report an issue: GitHub.