apple/pkl · error · CliException

`sourceModules` contains multiple modules named `docsite-inf

Error message

`sourceModules` contains multiple modules named `docsite-info.pkl`:
${docsiteInfoModuleUris.joinToString("\n")}

What it means

The pkl-doc CLI refuses to run when the `sourceModules` list contains more than one module named `docsite-info.pkl`. Each docsite can have exactly one docsite-info module defining its metadata, so duplicates are ambiguous. The error lists every URI found so the duplicate can be located.

Source

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

          docsiteInfoModuleUris.add(moduleUri)
        moduleUri.path?.endsWith("/doc-package-info.pkl", ignoreCase = true) ?: false ->
          packageInfoModuleUris.add(moduleUri)
        moduleUri.scheme == "package" -> {
          if (moduleUri.fragment != null) {
            throw CliException("Cannot generate documentation for just one module within a package")
          }
          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()

View on GitHub (pinned to f3efcbfc9b)

Solutions

  1. Remove all but one `docsite-info.pkl` module from the `sourceModules` arguments
  2. Check the URI list printed in the error to see which duplicate paths are being passed
  3. Deduplicate the argument list in your script/CI config

Example fix

// before
pkl-doc docsite-info.pkl ./site/docsite-info.pkl pkg1.pkl
// after
pkl-doc docsite-info.pkl pkg1.pkl
Defensive patterns

Strategy: validation

Validate before calling

val dupes = sourceModules.filter { it.fileName == "docsite-info.pkl" }
require(dupes.size <= 1) { "Multiple docsite-info.pkl passed: ${dupes.joinToString()}" }

Try / catch

try { pklDoc(args) } catch (e: CliException) { if (e.message?.startsWith("`sourceModules` contains multiple modules named") == true) { /* dedupe args and retry */ } else throw e }

Prevention

When it happens

Trigger: Running `pkl-doc` with multiple module arguments whose file name is `docsite-info.pkl`, e.g. passing docsite-info modules from two different directories or resolved via different paths to the same file.

Common situations: Accidentally passing both a local docsite-info.pkl and one from a dependency; listing the same directory twice with different path spellings; copy-pasting example commands that already include a docsite-info module.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

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