{"record":{"id":"03d51de4a48d1fc3","repo":"apple/pkl","slug":"cannot-generate-documentation-for-just-one-module","errorCode":null,"errorMessage":"Cannot generate documentation for just one module within a package","messagePattern":"Cannot generate documentation for just one module within a package","errorType":"exception","errorClass":"CliException","httpStatus":null,"severity":"error","filePath":"pkl-doc/src/main/kotlin/org/pkl/doc/CliDocGenerator.kt","lineNumber":177,"sourceCode":"    val regularModuleUris = mutableListOf<URI>()\n    val pklProjectPaths = mutableSetOf<Path>()\n    val packageUris = mutableListOf<PackageUri>()\n    for (moduleUri in options.base.normalizedSourceModules) {\n      if (moduleUri.scheme == \"file\") {\n        val dir = moduleUri.toPath().parent\n        val projectFile = dir.getProjectFile(options.base.normalizedRootDir)\n        if (projectFile != null) {\n          pklProjectPaths.add(projectFile)\n        }\n      }\n      when {\n        moduleUri.path?.endsWith(\"/docsite-info.pkl\", ignoreCase = true) ?: false ->\n          docsiteInfoModuleUris.add(moduleUri)\n        moduleUri.path?.endsWith(\"/doc-package-info.pkl\", ignoreCase = true) ?: false ->\n          packageInfoModuleUris.add(moduleUri)\n        moduleUri.scheme == \"package\" -> {\n          if (moduleUri.fragment != null) {\n            throw CliException(\"Cannot generate documentation for just one module within a package\")\n          }\n          try {\n            packageUris.add(PackageUri(moduleUri))\n          } catch (e: URISyntaxException) {\n            throw CliException(e.message!!)\n          }\n        }\n        else -> regularModuleUris.add(moduleUri)\n      }\n    }\n\n    if (docsiteInfoModuleUris.size > 1) {\n      throw CliException(\n        \"`sourceModules` contains multiple modules named `docsite-info.pkl`:\\n\" +\n          docsiteInfoModuleUris.joinToString(\"\\n\")\n      )\n    }\n","sourceCodeStart":159,"sourceCodeEnd":195,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-doc/src/main/kotlin/org/pkl/doc/CliDocGenerator.kt#L159-L195","documentation":"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.","triggerScenarios":"Passing a URI like pkg://example.com/foo@1.0.0#/some/module.pkl (fragment present) as a module argument to `pkldoc generate`.","commonSituations":"Copy-pasting a dependency-import URI (which includes a #module fragment) directly into pkldoc arguments.","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."],"exampleFix":"// before\npkldoc generate 'pkg://example.com/app@1.0.0#server.pkl'\n// after\npkldoc generate 'pkg://example.com/app@1.0.0'","handlingStrategy":"validation","validationCode":"fun String.isPackageModuleUri(): Boolean =\n  startsWith(\"pkg:\") && substringAfter('#', \"\").isNotEmpty() // strip fragment before passing to pkldoc","typeGuard":"fun String.toPkldocArg(): String =\n  if (startsWith(\"pkg:\")) substringBefore('#') else this","tryCatchPattern":"try {\n  pkldocGenerate(args)\n} catch (e: CliException) {\n  if (e.message == \"Cannot generate documentation for just one module within a package\") {\n    logger.error(\"Strip the #module fragment and pass the package URI instead\")\n  } else throw e\n}","preventionTips":["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."],"tags":["cli","packages","documentation","uri"],"backgroundTag":"unsupported-operation","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}