{"record":{"id":"ae1196ca4d898c0c","repo":"apple/pkl","slug":"errors-values-single-message-an-unexpected-e","errorCode":null,"errorMessage":"errors.values.single().message ?: \"An unexpected error occurred: \" + errors.values.single()","messagePattern":"errors\\.values\\.single\\(\\)\\.message \\?: \"An unexpected error occurred: \" \\+ errors\\.values\\.single\\(\\)","errorType":"exception","errorClass":"CliException","httpStatus":null,"severity":"error","filePath":"pkl-cli/src/main/kotlin/org/pkl/cli/CliPackageDownloader.kt","lineNumber":46,"sourceCode":") : CliCommand(baseOptions) {\n\n  override fun doRun() {\n    if (moduleCacheDir == null) {\n      throw CliException(\"Cannot download packages because no cache directory is specified.\")\n    }\n    val packageResolver = PackageResolver.getInstance(securityManager, httpClient, moduleCacheDir)\n    val errors = mutableMapOf<PackageUri, Throwable>()\n    for (pkg in packageUris) {\n      try {\n        packageResolver.downloadPackage(pkg, pkg.checksums, noTransitive)\n      } catch (e: Throwable) {\n        errors[pkg] = e\n      }\n    }\n    when (errors.size) {\n      0 -> return\n      1 ->\n        throw CliException(\n          errors.values.single().message\n            ?: (\"An unexpected error occurred: \" + errors.values.single())\n        )\n      else ->\n        throw CliException(\n          buildString {\n            appendLine(\"Failed to download some packages.\")\n            for ((uri, error) in errors) {\n              appendLine()\n              appendLine(\"Failed to download $uri because:\")\n              appendLine(\"${error.message}\")\n            }\n          }\n        )\n    }\n  }\n}\n","sourceCodeStart":28,"sourceCodeEnd":64,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-cli/src/main/kotlin/org/pkl/cli/CliPackageDownloader.kt#L28-L64","documentation":"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.","triggerScenarios":"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.","commonSituations":"Typo in a package URI or version; package removed from the registry; transient network outage during `pkl package download`.","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."],"exampleFix":"# before\npkl package download package://example.com/foo@1.0.0  # 404: not found\n# after\npkl package download package://example.com/foo@1.1.0","handlingStrategy":"retry","validationCode":"// pre-check the package resolves before downloading\nval head = httpClient.head(\"https://example.com/foo%401.1.0\")\nrequire(head.status == 200) { \"package not found at remote\" }","typeGuard":null,"tryCatchPattern":"try {\n  pklCli.runPackageDownload(uris)\n} catch (e: CliException) {\n  if (e.message?.contains(\"Failed to download\") == true && transient(e)) retryWithBackoff()\n  else throw e\n}","preventionTips":["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."],"tags":["cli","package-download","network"],"backgroundTag":"http-request-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"}