apple/pkl · error · CliException

errors.values.single().message ?: "An unexpected error…

Error message

errors.values.single().message ?: "An unexpected error occurred: " + errors.values.single()

What it means

When exactly one package fails to download, `pkl package download` rethrows that package's error message as a CliException; if the underlying error has no message, it prefixes "An unexpected error occurred: " with the exception's toString. This surfaces the single failure's cause directly.

Solutions

Fix the cause reported in the message: correct the package URI/version, fix network access, or verify checksums.
Retry the command if the failure was transient.
If several packages fail, the multi-error variant of this message will list each URI and cause instead.

Example fix

# before
pkl package download package://example.com/foo@1.0.0  # 404: not found
# after
pkl package download package://example.com/foo@1.1.0

Defensive patterns

Strategy: retry

Validate before calling

// pre-check the package resolves before downloading
val head = httpClient.head("https://example.com/foo%401.1.0")
require(head.status == 200) { "package not found at remote" }

Try / catch

try {
  pklCli.runPackageDownload(uris)
} catch (e: CliException) {
  if (e.message?.contains("Failed to download") == true && transient(e)) retryWithBackoff()
  else throw e
}

Prevention

Verify package URIs and versions against the registry before downloading.
Check network/proxy availability in CI.
Pin checksums only after confirming the exact package version exists.

When it happens

Trigger: Downloading multiple packages where exactly one fails — e.g. a bad checksum, a 404 from a remote repository, or a network failure for one URI.

Common situations: Typo in a package URI or version; package removed from the registry; transient network outage during `pkl package download`.

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/ae1196ca4d898c0c. Report an issue: GitHub.

Appendix: source

Thrown at pkl-cli/src/main/kotlin/org/pkl/cli/CliPackageDownloader.kt:46

) : CliCommand(baseOptions) {

  override fun doRun() {
    if (moduleCacheDir == null) {
      throw CliException("Cannot download packages because no cache directory is specified.")
    }
    val packageResolver = PackageResolver.getInstance(securityManager, httpClient, moduleCacheDir)
    val errors = mutableMapOf<PackageUri, Throwable>()
    for (pkg in packageUris) {
      try {
        packageResolver.downloadPackage(pkg, pkg.checksums, noTransitive)
      } catch (e: Throwable) {
        errors[pkg] = e
      }
    }
    when (errors.size) {
      0 -> return
      1 ->
        throw CliException(
          errors.values.single().message
            ?: ("An unexpected error occurred: " + errors.values.single())
        )
      else ->
        throw CliException(
          buildString {
            appendLine("Failed to download some packages.")
            for ((uri, error) in errors) {
              appendLine()
              appendLine("Failed to download $uri because:")
              appendLine("${error.message}")
            }
          }
        )
    }
  }
}

View on GitHub (pinned to f3efcbfc9b)