{"record":{"id":"d0fa8ea0436b70ec","repo":"apple/pkl","slug":"failed-to-package-metadata-for-this-e-message","errorCode":null,"errorMessage":"Failed to package metadata for $this: ${e.message}","messagePattern":"Failed to package metadata for \\$this: (.+?)","errorType":"exception","errorClass":"CliException","httpStatus":null,"severity":"error","filePath":"pkl-doc/src/main/kotlin/org/pkl/doc/CliDocGenerator.kt","lineNumber":111,"sourceCode":"            name = metadata.name,\n            uri = dependency.packageUri.uri,\n            version = metadata.version.toString(),\n            sourceCode = metadata.sourceCode,\n            sourceCodeUrlScheme = metadata.sourceCodeUrlScheme,\n            documentation = metadata.documentation,\n          )\n        add(packageDependency)\n      }\n      add(stdlibDependency)\n    }\n  }\n\n  private fun PackageUri.toDocPackageInfo(): DocPackageInfo {\n    val (metadata, checksum) =\n      try {\n        packageResolver.getDependencyMetadataAndComputeChecksum(this)\n      } catch (e: PackageLoadError) {\n        throw CliException(\"Failed to package metadata for $this: ${e.message}\")\n      }\n    return DocPackageInfo(\n      name = \"${uri.authority}${uri.path.substringBeforeLast('@')}\",\n      moduleNamePrefix = \"${metadata.name}.\",\n      version = metadata.version.toString(),\n      importUri = toPackageAssetUri(\"/\").toString(),\n      uri = uri,\n      authors = metadata.authors,\n      issueTracker = metadata.issueTracker,\n      dependencies = metadata.getPackageDependencies(),\n      overview = metadata.description,\n      extraAttributes = mapOf(\"Checksum\" to checksum.sha256),\n      sourceCode = metadata.sourceCode,\n      sourceCodeUrlScheme = metadata.sourceCodeUrlScheme,\n      annotations = metadata.annotations,\n    )\n  }\n","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-doc/src/main/kotlin/org/pkl/doc/CliDocGenerator.kt#L93-L129","documentation":"When generating docs for the current package itself, toDocPackageInfo calls getDependencyMetadataAndComputeChecksum; a PackageLoadError (the package cannot be loaded — invalid PklProject, missing package metadata, unresolvable URI) is converted to this CliException.","triggerScenarios":"Running pkldoc against a package whose own metadata cannot be loaded: malformed/missing PklProject file, invalid package name/version fields, or package URI unresolvable while computing checksums.","commonSituations":"Running pkldoc in a directory without a valid PklProject; PklProject with schema violations (bad apiVersion, missing name); wrong cwd passed to the CLI.","solutions":["Read the wrapped PackageLoadError message for the specific problem (missing file, invalid field).","Validate PklProject with `pkl project resolve` or `pkl eval PklProject` before generating docs.","Run pkldoc from the project root so PklProject is discoverable.","Fix package name/version fields to satisfy the PklProject schema."],"exampleFix":"// before\npkldoc generate src/some/nested/dir\n// after\ncd project-root && pkldoc generate .","handlingStrategy":"validation","validationCode":"// pre-flight: the project itself must load\n// pkl eval PklProject && pkl project resolve --project-dir .","typeGuard":"fun isPkldocSafe(projectDir: Path): Boolean =\n  java.io.File(projectDir.toFile(), \"PklProject\").exists()","tryCatchPattern":"try {\n  generateDocs(projectRoot)\n} catch (e: CliException) {\n  if (e.message?.startsWith(\"Failed to package metadata\") == true) {\n    logger.error(\"Invalid or missing PklProject in $projectRoot: ${e.message}\")\n  } else throw e\n}","preventionTips":["Always run pkldoc from the directory containing a valid PklProject.","Validate PklProject with `pkl eval PklProject` before doc generation.","Keep name/version/api fields conforming to the PklProject schema."],"tags":["packages","cli","documentation"],"backgroundTag":"package-load-failed","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"}