What causes "install failed: %w" in hasura/graphql-engine?

Read the wrapped error after the colon to identify the actual failing step (download, staging dir, move, or symlink)

install failed: %w

Error message

install failed: %w

What it means

This is a wrapper error: Install() delegates the actual download/extract/link work to the private installPlugin() and any failure there (staging dir creation, download/extract, moving files, absolute-path resolution, or symlink creation) is re-wrapped as "install failed: %w". The real cause is in the chained error text; this message only tells you the failure happened during the installation phase.

Source

Thrown at cli/plugins/plugins.go:222

	var op errors.Op = "plugins.Config.Install"
	// Find available installation platform
	platform, ok, err := MatchPlatform(plugin.Platforms)
	if err != nil {
		return errors.E(
			op,
			fmt.Errorf("failed trying to find a matching platform in plugin spec: %w", err),
		)
	}

	if !ok {
		return errors.E(
			op,
			fmt.Errorf("plugin %q does not offer installation for this platform", plugin.Name),
		)
	}

	if err := c.installPlugin(plugin, platform); err != nil {
		return errors.E(op, fmt.Errorf("install failed: %w", err))
	}

	err = c.StoreManifest(plugin, c.Paths.PluginInstallReceiptPath(plugin.Name))
	if err != nil {
		return errors.E(
			op,
			fmt.Errorf("installation receipt could not be stored, uninstall may fail: %w", err),
		)
	}

	return nil
}

// Uninstall will uninstall a plugin.
func (c *Config) Uninstall(name string) error {
	var op errors.Op = "plugins.Config.Uninstall"

	if _, err := c.LoadManifest(c.Paths.PluginInstallReceiptPath(name)); err != nil {

View on GitHub (pinned to 724551b9ae)

Solutions

Read the wrapped error after the colon to identify the actual failing step (download, staging dir, move, or symlink)
If it is a download/checksum failure, verify platform.URI is reachable and platform.Sha256 matches the artifact currently at that URL
If it is a permissions failure, fix ownership of the plugin download/install/bin directories (e.g. rm -rf the stale dir or chown it) and avoid mixing sudo and non-sudo installs
Retry after clearing the staging directory (the plugins download cache dir) in case of a corrupted partial download

Defensive patterns

Strategy: try-catch

Try / catch

if err := cfg.Install(plugin); err != nil {
	var inner error
	if errors.As(err, &inner) { /* inspect wrapped cause */ }
	switch {
	case strings.Contains(err.Error(), "unpack into staging"):
		// network/checksum: retry after clearing cache
	default:
		// permissions/fs: repair directories then retry
	}
}

Prevention

Pre-check writability of download, install, and bin directories before installing
Verify artifact URLs and checksums are current before invoking Install
Run installs consistently as the same user to avoid mixed-ownership directories

When it happens

Trigger: Any failure inside installPlugin: network error or checksum mismatch during downloadAndExtract, permission denied creating the staging dir under the download path, failure moving files into the versioned install directory, or failure symlinking the binary into the bin path.

Common situations: Corporate proxy blocking the artifact download; sha256 mismatch because the manifest points at a stale artifact URL; read-only or root-owned plugin directories from a previous sudo install; disk full during extraction.

Related errors

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