hasura/graphql-engine · error

failed to unpack into staging dir: %w

Error message

failed to unpack into staging dir: %w

What it means

installPlugin() calls downloadAndExtract(stagingDir, platform.URI, platform.Sha256) to fetch the platform artifact, verify its sha256, and unpack it into the staging directory. Any failure there — network error, HTTP 404, checksum mismatch, archive format problem, or write error while extracting — surfaces wrapped in this error.

Source

Thrown at cli/plugins/plugins.go:306

		err := os.MkdirAll(downloadStagingDir, 0o755)
		if err != nil {
			return errors.E(
				op,
				fmt.Errorf("could not create staging dir %q: %w", downloadStagingDir, err),
			)
		}
		defer func() {
			c.Logger.Debugf("Deleting the download staging directory %s", downloadStagingDir)

			err := os.RemoveAll(downloadStagingDir)
			if err != nil {
				c.Logger.Debugf("failed to clean up download staging directory: %s", err)
			}
		}()

		err = downloadAndExtract(downloadStagingDir, platform.URI, platform.Sha256)
		if err != nil {
			return errors.E(op, fmt.Errorf("failed to unpack into staging dir: %w", err))
		}

		err = moveToInstallDir(downloadStagingDir, installDir, platform.Files)
		if err != nil {
			return errors.E(
				op,
				fmt.Errorf("failed while moving files to the installation directory: %w", err),
			)
		}
	}

	subPathAbs, err := filepath.Abs(installDir)
	if err != nil {
		return errors.E(
			op,
			fmt.Errorf("failed to get the absolute fullPath of %q: %w", installDir, err),
		)
	}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Verify platform.URI in the plugin manifest resolves to a real artifact (curl -I the URL)
2. Compare the artifact's actual sha256 with platform.Sha256 in the manifest — if they differ, the manifest pins a stale hash and must be updated or a newer plugin version used
3. Check network/proxy/DNS if the download itself fails; unset or configure proxy env vars as needed
4. Clear the staging/download directory and retry to rule out a corrupted partial download

Example fix

# before: stale checksum in manifest
"sha256": "oldhash..."
# after: recompute against current artifact
$ curl -sL https://example.com/myplugin-linux-amd64.zip | sha256sum
"sha256": "newhash..."

// verify artifact URL and checksum before installing
resp, err := http.Head(platform.URI)
if err != nil || resp.StatusCode != http.StatusOK { /* fix URL first */ }
h, _ := sha256fileOfDownloaded(platform.URI) // compare with platform.Sha256

err := cfg.Install(plugin)
if err != nil && strings.Contains(err.Error(), "failed to unpack into staging dir") {
	// distinguish checksum vs network via the wrapped text;
	// network failures: retry with backoff; checksum failures: update the manifest hash
}

When it happens

Trigger: The platform.URI download fails (offline, proxy, DNS), returns 404/403 because the release artifact was moved or deleted, the downloaded artifact's hash does not match platform.Sha256, or the archive is corrupt / not a supported archive format.

Common situations: Plugin author re-published a release so the pinned sha256 no longer matches; artifact URL from an old manifest is dead; corporate proxy or firewall blocks the download; truncated download on flaky networks; artifact uploaded in an unpackable format.

Related errors

• failed to unpack the plugin archive: %w
• install failed: %w
• failed to obtain plugin archive: %w
• could not read archive: %w
• plugin %q does not offer installation for this platform

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