apple/pkl · error · CliException

`sourceModules` must contain at least one module named…

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.

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.

Appendix: 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)