{"record":{"id":"cdf11d6dc53228ae","repo":"apple/pkl","slug":"could-not-find-a-doc-package-info-pkl-for-module","errorCode":null,"errorMessage":"Could not find a doc-package-info.pkl for module $uri","messagePattern":"Could not find a doc-package-info\\.pkl for module \\$uri","errorType":"exception","errorClass":"CliException","httpStatus":null,"severity":"error","filePath":"pkl-doc/src/main/kotlin/org/pkl/doc/CliDocGenerator.kt","lineNumber":263,"sourceCode":"              DocsiteInfo.fromPkl(module).apply {\n                evaluator.collectImportedModules(overviewImports)\n              }\n            }\n          }\n\n        for (uri in packageInfoModuleUris) {\n          val module = evaluator.evaluate(ModuleSource.uri(uri))\n          val docPackageInfo =\n            DocPackageInfo.fromPkl(module).apply {\n              evaluator.collectImportedModules(overviewImports)\n            }\n          schemasByDocPackageInfoAndPath[docPackageInfo to uri.toPath().parent] = mutableSetOf()\n        }\n\n        for (uri in regularModuleUris) {\n          val entry =\n            schemasByDocPackageInfoAndPath.keys.find { uri.toPath().startsWith(it.second) }\n              ?: throw CliException(\"Could not find a doc-package-info.pkl for module $uri\")\n          val schema =\n            evaluator.evaluateSchema(ModuleSource.uri(uri)).apply {\n              evaluator.collectImportedModules(imports)\n            }\n          schemasByDocPackageInfoAndPath[entry]!!.add(schema)\n        }\n\n        // doc generator resolves `pkl.base` even if not imported explicitly\n        val pklBaseUri = URI(\"pkl:base\")\n        importedModules[pklBaseUri] = evaluator.evaluateSchema(ModuleSource.uri(pklBaseUri))\n      }\n    } finally {\n      Closeables.closeQuietly(builder.moduleKeyFactories)\n      Closeables.closeQuietly(builder.resourceReaders)\n    }\n\n    val versions = mutableMapOf<String, Version>()\n    val versionComparator =","sourceCodeStart":245,"sourceCodeEnd":281,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-doc/src/main/kotlin/org/pkl/doc/CliDocGenerator.kt#L245-L281","documentation":"Every regular module passed to pkl-doc must fall under the parent path of some `doc-package-info.pkl` module, since package metadata scopes documentation. When a module's path does not start with any known doc-package-info parent directory, generation aborts with this error naming the offending module URI.","triggerScenarios":"Passing a module URI whose path is outside the directory tree of every `doc-package-info.pkl` in `sourceModules`, e.g. documenting `shared/Util.pkl` when the package-info lives in `packages/mypkg/`.","commonSituations":"Module placed outside the package root by mistake; mixing modules from multiple directories with only one doc-package-info.pkl; typos or differing relative-path bases in the CLI arguments.","solutions":["Move the module under the directory of an existing `doc-package-info.pkl`, or","Add a `doc-package-info.pkl` in the module's parent directory and pass it in sourceModules","Verify the module URI/path in the error matches the intended package root"],"exampleFix":"// before\npkl-doc docsite-info.pkl pkg/doc-package-info.pkl other/Stray.pkl\n// after (move Stray.pkl under pkg/ or add its own doc-package-info.pkl)\npkl-doc docsite-info.pkl pkg/doc-package-info.pkl pkg/Stray.pkl","handlingStrategy":"validation","validationCode":"val pkgRoots = docPackageInfoUris.map { it.toPath().parent }\nval strays = regularModuleUris.filter { uri -> pkgRoots.none { uri.toPath().startsWith(it) } }\nrequire(strays.isEmpty()) { \"Modules outside any doc-package-info scope: $strays\" }","typeGuard":null,"tryCatchPattern":"try { pklDoc(args) } catch (e: CliException) { if (e.message?.startsWith(\"Could not find a doc-package-info.pkl\") == true) { /* move module or add package-info for its dir */ } else throw e }","preventionTips":["Keep all documented modules under the package-info directory","Add a doc-package-info.pkl for each independent module root","Verify paths resolve relative to the same base directory"],"tags":["cli","module-resolution","path-scope"],"backgroundTag":"resource-not-found","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"}