apple/pkl · error · CliException

Failed to fetch dependency metadata for

Error message

Failed to fetch dependency metadata for ${dependency.packageUri}: ${e.message}

What it means

pkldoc generation fetches metadata for each dependency of the documented package via packageResolver.getDependencyMetadata. When that fetch fails for any reason (network error, missing package, bad checksums), it is wrapped in this CliException naming the dependency's package URI and the underlying message.

Solutions

Read the wrapped e.message for the root cause (DNS failure, 404, checksum mismatch) and address that.
Verify the dependency's package URI, version, and checksums in PklProject against the registry.
Check network/proxy connectivity to the package repository; retry if transient.
Run `pkl project resolve` (or the equivalent resolve step) first to confirm dependencies can be fetched.
For private registries, ensure credentials/repository configuration is present.

Example fix

// before (PklProject dependencies)
"my-dep": { uri: "pkg://example.com/my@1.0.0" } // version deleted upstream
// after
"my-dep": { uri: "pkg://example.com/my@1.0.1" }

Defensive patterns

Strategy: try-catch

Validate before calling

// before generating, verify deps resolve:
// pkl project resolve --project-dir .  (non-zero exit => deps unresolvable)

Try / catch

try {
  generateDocs()
} catch (e: CliException) {
  if (e.message?.startsWith("Failed to fetch dependency metadata") == true) {
    logger.error("Dependency resolution failed: ${e.message}. Check registry connectivity and PklProject checksums.")
  } else throw e
}

Prevention

Run dependency resolution as a separate CI step before doc generation.
Pin dependency versions and checksums; verify they exist on the registry.
Configure proxy/credentials for private package repositories in the build environment.
Retry generation on transient network failures.

When it happens

Trigger: Running pkldoc generation for a package whose dependencies cannot be resolved: unreachable registry, wrong dependency URI/version in PklProject, checksum mismatch, or authentication failure against a private registry.

Common situations: Offline CI runner; private dependency not in the configured repository; dependency version deleted from the remote; proxy blocking the registry host.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

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

Appendix: source

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

  private val versions = mutableMapOf<String, Version>()

  private val versionComparator =
    Comparator<String> { v1, v2 ->
      versions
        .getOrPut(v1) { Version.parse(v1) }
        .compareTo(versions.getOrPut(v2) { Version.parse(v2) })
    }

  private val docMigrator = DocMigrator(options.outputDir, System.out, versionComparator)

  private fun DependencyMetadata.getPackageDependencies(): List<DocPackageInfo.PackageDependency> {
    return buildList {
      for ((_, dependency) in dependencies) {
        val metadata =
          try {
            packageResolver.getDependencyMetadata(dependency.packageUri, dependency.checksums)
          } catch (e: Exception) {
            throw CliException(
              "Failed to fetch dependency metadata for ${dependency.packageUri}: ${e.message}"
            )
          }
        val packageDependency =
          DocPackageInfo.PackageDependency(
            name = metadata.name,
            uri = dependency.packageUri.uri,
            version = metadata.version.toString(),
            sourceCode = metadata.sourceCode,
            sourceCodeUrlScheme = metadata.sourceCodeUrlScheme,
            documentation = metadata.documentation,
          )
        add(packageDependency)
      }
      add(stdlibDependency)
    }
  }

View on GitHub (pinned to f3efcbfc9b)