hasura/graphql-engine · error

failed to unpack the plugin archive: %w

Error message

failed to unpack the plugin archive: %w

What it means

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.

Source

Thrown at cli/plugins/util.go:164

	var op errors.Op = "plugins.downloadAndExtract"

	nurl, err := url.Parse(uri)
	if err != nil {
		return errors.E(op, fmt.Errorf("unable to parse uri: %w", err))
	}

	var fetcher download.Fetcher
	if nurl.Scheme == "file" {
		fetcher = download.NewFileFetcher(nurl.Path)
	} else {
		fetcher = download.HTTPFetcher{}
	}

	verifier := download.NewSha256Verifier(sha256sum)

	err = download.NewDownloader(verifier, fetcher).Get(uri, extractDir)
	if err != nil {
		return errors.E(op, fmt.Errorf("failed to unpack the plugin archive: %w", err))
	}

	return nil
}

// IsWindows sees runtime.GOOS to find out if current execution mode is win32.
func IsWindows() bool {
	goos := runtime.GOOS

	return goos == "windows"
}

func createOrUpdateLink(binDir, binary, plugin string) error {
	var op errors.Op = "plugins.createOrUpdateLink"

	dst := filepath.Join(binDir, PluginNameToBin(plugin, IsWindows()))

	err := removeLink(dst)

View on GitHub (pinned to 724551b9ae)

Solutions

1. Read the wrapped download error to classify: checksum mismatch → recompute and update sha256 in the manifest; 404 → fix url; timeout → retry/check network.
2. Verify the remote asset exists (curl -I <url>) and its sha256sum matches the manifest field exactly.
3. For local testing use a file:// URI to rule out network issues.

Example fix

# before
# manifest sha256 = <old release hash>
$ sha256sum /tmp/asset.tar.gz   # differs

# after
# update manifest:
"sha256": "<output of sha256sum asset.tar.gz>"

resp, err := http.Head(pl.Url)
if err != nil || resp.StatusCode != 200 {
	return fmt.Errorf("asset unreachable: %s (status %d)", pl.Url, resp.StatusCode)
}
// optionally pre-verify checksum of a locally mirrored asset

if err := plugins.Install(...); err != nil {
	if strings.Contains(err.Error(), "failed to unpack") {
		// inspect cause: checksum mismatch → fix manifest sha256;
		// transient network → retry with backoff
	}
}

When it happens

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

Common situations: 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.

Related errors

• failed to unpack into staging dir: %w
• install failed: %w
• plugin %q does not offer installation for this platform
• installation receipt could not be stored, uninstall may fail
• could not create staging dir %q: %w

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/f875d1ec78dbd353. Report an issue: GitHub.