apple/pkl · error · CliException

Cannot generate documentation for just one module within a…

Error message

Cannot generate documentation for just one module within a package

What it means

pkldoc generates documentation for whole packages, not individual modules. When a module URI uses the package scheme and carries a fragment (selecting a single module inside a package), generation is rejected because per-module documentation within a package is unsupported.

Solutions

Remove the fragment: pass pkg://example.com/foo@1.0.0 to document the whole package.
Document the package that contains the module rather than the single module URI.
For a standalone (non-packaged) module, use its file: or regular https: URI without the package scheme.

Example fix

// before
pkldoc generate 'pkg://example.com/app@1.0.0#server.pkl'
// after
pkldoc generate 'pkg://example.com/app@1.0.0'

Defensive patterns

Strategy: validation

Validate before calling

fun String.isPackageModuleUri(): Boolean =
  startsWith("pkg:") && substringAfter('#', "").isNotEmpty() // strip fragment before passing to pkldoc

Type guard

fun String.toPkldocArg(): String =
  if (startsWith("pkg:")) substringBefore('#') else this

Try / catch

try {
  pkldocGenerate(args)
} catch (e: CliException) {
  if (e.message == "Cannot generate documentation for just one module within a package") {
    logger.error("Strip the #module fragment and pass the package URI instead")
  } else throw e
}

Prevention

Pass whole package URIs (pkg://host/name@version) to pkldoc, never URIs with #fragments.
When scripting around dependency imports, normalize URIs with substringBefore('#').
Use plain file/https module URIs only for standalone modules outside packages.

When it happens

Trigger: Passing a URI like pkg://example.com/foo@1.0.0#/some/module.pkl (fragment present) as a module argument to `pkldoc generate`.

Common situations: Copy-pasting a dependency-import URI (which includes a #module fragment) directly into pkldoc arguments.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

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

    val regularModuleUris = mutableListOf<URI>()
    val pklProjectPaths = mutableSetOf<Path>()
    val packageUris = mutableListOf<PackageUri>()
    for (moduleUri in options.base.normalizedSourceModules) {
      if (moduleUri.scheme == "file") {
        val dir = moduleUri.toPath().parent
        val projectFile = dir.getProjectFile(options.base.normalizedRootDir)
        if (projectFile != null) {
          pklProjectPaths.add(projectFile)
        }
      }
      when {
        moduleUri.path?.endsWith("/docsite-info.pkl", ignoreCase = true) ?: false ->
          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")
      )
    }

View on GitHub (pinned to f3efcbfc9b)