hasura/graphql-engine · error

failed to install new version: %w

Error message

failed to install new version: %w

What it means

This error is thrown by the plugin Upgrade flow when the newly downloaded plugin version fails to install after the old version was already uninstalled. It wraps the underlying error from installPlugin, which typically covers copying the plugin binary into the versioned install directory. Because it occurs mid-upgrade, the plugin may be left uninstalled.

Source

Thrown at cli/plugins/plugins.go:448

	// See if it's a newer version
	if installReceipt.ParsedVersion != nil {
		if !installReceipt.ParsedVersion.LessThan(plugin.ParsedVersion) ||
			installReceipt.ParsedVersion.Equal(plugin.ParsedVersion) {
			return plugin, errors.E(op, ErrIsAlreadyUpgraded)
		}
	}

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

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

	// Clean old installations
	err = os.RemoveAll(c.Paths.PluginVersionInstallPath(plugin.Name, installReceipt.Version))
	if err != nil {
		return plugin, errors.E(op, err)
	}

	return plugin, nil
}

func (c *Config) LoadManifest(path string) (Plugin, error) {
	var op errors.Op = "plugins.Config.LoadManifest"

	plugin, err := c.ReadPluginFromFile(path)
	if err != nil {
		return plugin, errors.E(op, err)
	}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check that the plugin's index manifest actually publishes an artifact for your GOOS/GOARCH platform and version
2. Verify write permissions and free disk space on the plugin install path (Paths.PluginVersionInstallPath)
3. Retry the upgrade after a failed partial install; if it still fails, reinstall the plugin from scratch with Install to restore a working state
4. Inspect the wrapped error chain (errors.Unwrap / %w) to see the exact installPlugin failure

Example fix

# before
mycli plugin upgrade grafana-dashboard
# Error: plugins.Config.Upgrade: failed to install new version: ...

# after: verify platform artifact exists in the plugin index, then
mycli plugin install grafana-dashboard --version 1.2.3

if _, err := cfg.LoadPluginByName(name); err != nil { /* don't attempt upgrade */ }
if runtime.GOOS+"/"+runtime.GOARCH != plugin.SupportedPlatform { /* skip upgrade */ }

plugin, err := cfg.Upgrade(name, platform)
if err != nil {
	var target *plugins.Plugin // if typed errors available; otherwise inspect message
	if strings.Contains(err.Error(), "failed to install new version") {
		// plugin may be uninstalled now: reinstall last known good version
		_, _ = cfg.Install(name, lastGoodVersion, platform)
	}
	return err
}

When it happens

Trigger: Calling Config.Upgrade (via the CLI plugin upgrade command / Run) when the old version was removed but reinstalling the new platform-specific plugin artifact fails: download artifact missing for the platform, disk full, or the versioned install path is not writable.

Common situations: Upgrading a plugin whose remote index entry lacks an artifact for linux/arm64 or another uncommon platform; permissions changed on the plugins directory; running as a different user than the one who installed the plugins; disk exhaustion during copy.

Related errors

• installation receipt could not be stored, uninstall may fail
• could not create staging dir %q: %w
• failed while moving files to the installation directory: %w
• failed to ensure create directory %q: %w
• failed to remove old symlink: %w

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