{"record":{"id":"f875d1ec78dbd353","repo":"hasura/graphql-engine","slug":"failed-to-unpack-the-plugin-archive-w","errorCode":null,"errorMessage":"failed to unpack the plugin archive: %w","messagePattern":"failed to unpack the plugin archive: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/plugins/util.go","lineNumber":164,"sourceCode":"\tvar op errors.Op = \"plugins.downloadAndExtract\"\n\n\tnurl, err := url.Parse(uri)\n\tif err != nil {\n\t\treturn errors.E(op, fmt.Errorf(\"unable to parse uri: %w\", err))\n\t}\n\n\tvar fetcher download.Fetcher\n\tif nurl.Scheme == \"file\" {\n\t\tfetcher = download.NewFileFetcher(nurl.Path)\n\t} else {\n\t\tfetcher = download.HTTPFetcher{}\n\t}\n\n\tverifier := download.NewSha256Verifier(sha256sum)\n\n\terr = download.NewDownloader(verifier, fetcher).Get(uri, extractDir)\n\tif err != nil {\n\t\treturn errors.E(op, fmt.Errorf(\"failed to unpack the plugin archive: %w\", err))\n\t}\n\n\treturn nil\n}\n\n// IsWindows sees runtime.GOOS to find out if current execution mode is win32.\nfunc IsWindows() bool {\n\tgoos := runtime.GOOS\n\n\treturn goos == \"windows\"\n}\n\nfunc createOrUpdateLink(binDir, binary, plugin string) error {\n\tvar op errors.Op = \"plugins.createOrUpdateLink\"\n\n\tdst := filepath.Join(binDir, PluginNameToBin(plugin, IsWindows()))\n\n\terr := removeLink(dst)","sourceCodeStart":146,"sourceCodeEnd":182,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/cli/plugins/util.go#L146-L182","documentation":"downloadAndExtract runs download.NewDownloader(NewSha256Verifier(sha256sum), fetcher).Get(uri, extractDir). Any failure in fetching, checksum verification, or extraction is aggregated and wrapped as 'failed to unpack the plugin archive'. The underlying download package error carries the real cause.","triggerScenarios":"installPlugin with: a 404 on the release URL, a network timeout, a sha256 mismatch between the manifest and the downloaded archive, or a corrupt/unsupported archive format that fails extraction.","commonSituations":"Releasing a new binary but forgetting to update sha256 in the manifest; release assets not yet uploaded when users install; proxies/firewalls blocking the download; publishing .zip while the pipeline expects .tar.gz.","solutions":["Read the wrapped download error to classify: checksum mismatch → recompute and update sha256 in the manifest; 404 → fix url; timeout → retry/check network.","Verify the remote asset exists (curl -I <url>) and its sha256sum matches the manifest field exactly.","For local testing use a file:// URI to rule out network issues."],"exampleFix":"# before\n# manifest sha256 = <old release hash>\n$ sha256sum /tmp/asset.tar.gz   # differs\n\n# after\n# update manifest:\n\"sha256\": \"<output of sha256sum asset.tar.gz>\"","handlingStrategy":"retry","validationCode":"resp, err := http.Head(pl.Url)\nif err != nil || resp.StatusCode != 200 {\n\treturn fmt.Errorf(\"asset unreachable: %s (status %d)\", pl.Url, resp.StatusCode)\n}\n// optionally pre-verify checksum of a locally mirrored asset","typeGuard":null,"tryCatchPattern":"if err := plugins.Install(...); err != nil {\n\tif strings.Contains(err.Error(), \"failed to unpack\") {\n\t\t// inspect cause: checksum mismatch → fix manifest sha256;\n\t\t// transient network → retry with backoff\n\t}\n}","preventionTips":["Automate sha256 updates in the manifest as part of the release step.","Upload release assets before publishing the manifest.","Pin exact asset URLs, not mutable 'latest' links.","Retry transient network failures with backoff before failing hard."],"tags":["plugins","download","checksum","extraction","install"],"backgroundTag":"download-checksum-mismatch","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}