apple/pkl · error · CliException

Failed to package metadata for $this

Error message

Failed to package metadata for $this: ${e.message}

What it means

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.

Solutions

1. Read the wrapped PackageLoadError message for the specific problem (missing file, invalid field).
2. Validate PklProject with `pkl project resolve` or `pkl eval PklProject` before generating docs.
3. Run pkldoc from the project root so PklProject is discoverable.
4. Fix package name/version fields to satisfy the PklProject schema.

Example fix

// before
pkldoc generate src/some/nested/dir
// after
cd project-root && pkldoc generate .

// pre-flight: the project itself must load
// pkl eval PklProject && pkl project resolve --project-dir .

fun isPkldocSafe(projectDir: Path): Boolean =
  java.io.File(projectDir.toFile(), "PklProject").exists()

try {
  generateDocs(projectRoot)
} catch (e: CliException) {
  if (e.message?.startsWith("Failed to package metadata") == true) {
    logger.error("Invalid or missing PklProject in $projectRoot: ${e.message}")
  } else throw e
}

When it happens

Trigger: 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.

Common situations: Running pkldoc in a directory without a valid PklProject; PklProject with schema violations (bad apiVersion, missing name); wrong cwd passed to the CLI.

Related errors

• Cannot generate documentation for just one module within a…
• Failed to fetch dependency metadata for
• pkldoc website model is too old
• Cannot download packages because no cache directory is…
• Cannot generate JUnit report for $moduleUri. A report with…

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

Appendix: source

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

            name = metadata.name,
            uri = dependency.packageUri.uri,
            version = metadata.version.toString(),
            sourceCode = metadata.sourceCode,
            sourceCodeUrlScheme = metadata.sourceCodeUrlScheme,
            documentation = metadata.documentation,
          )
        add(packageDependency)
      }
      add(stdlibDependency)
    }
  }

  private fun PackageUri.toDocPackageInfo(): DocPackageInfo {
    val (metadata, checksum) =
      try {
        packageResolver.getDependencyMetadataAndComputeChecksum(this)
      } catch (e: PackageLoadError) {
        throw CliException("Failed to package metadata for $this: ${e.message}")
      }
    return DocPackageInfo(
      name = "${uri.authority}${uri.path.substringBeforeLast('@')}",
      moduleNamePrefix = "${metadata.name}.",
      version = metadata.version.toString(),
      importUri = toPackageAssetUri("/").toString(),
      uri = uri,
      authors = metadata.authors,
      issueTracker = metadata.issueTracker,
      dependencies = metadata.getPackageDependencies(),
      overview = metadata.description,
      extraAttributes = mapOf("Checksum" to checksum.sha256),
      sourceCode = metadata.sourceCode,
      sourceCodeUrlScheme = metadata.sourceCodeUrlScheme,
      annotations = metadata.annotations,
    )
  }

View on GitHub (pinned to f3efcbfc9b)