hasura/graphql-engine · error

failed while moving files to the installation directory: %w

Error message

failed while moving files to the installation directory: %w

What it means

After a successful download, installPlugin() moves the declared files from the staging directory into the versioned install directory (PluginVersionInstallPath) via moveToInstallDir. This error wraps any failure during that move/copy — typically a missing declared file in the archive, or a filesystem error creating or writing into the install directory.

Source

Thrown at cli/plugins/plugins.go:313

		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),
		)
	}

	fullPath := filepath.Join(installDir, filepath.FromSlash(platform.Bin))

	pathAbs, err := filepath.Abs(fullPath)
	if err != nil {
		return errors.E(
			op,

View on GitHub (pinned to 724551b9ae)

Solutions

1. Extract the downloaded artifact manually and compare its contents against platform.Files in the plugin manifest; fix the manifest (or use a plugin version where they match)
2. Verify the install directory path can be created and written by the current user; fix ownership if a previous privileged install left root-owned dirs
3. Free disk space if the copy fails with ENOSPC
4. Clear both the staging and install directories and retry to eliminate partial-state issues

Example fix

// before: manifest lists a file the archive doesn't contain
"files": { "myplugin-linux-amd64": "myplugin" }
// after: match the archive's real layout
"files": { "bin/myplugin": "myplugin" }

// sanity-check that declared files can plausibly exist in the artifact
for declared := range platform.Files {
	if strings.Contains(declared, "..") || declared == "" {
		// reject suspicious manifest before install
	}
}

if err := cfg.Install(plugin); err != nil && strings.Contains(err.Error(), "moving files to the installation directory") {
	// likely a Files/archive layout mismatch: extract the artifact and align the manifest
}

When it happens

Trigger: moveToInstallDir failing because a path listed in platform.Files does not exist in the extracted archive, the install directory cannot be created (permissions, disk full), or a cross-device move with a copy fallback hitting a write error.

Common situations: Plugin manifest's Files list references paths that do not match the archive's internal layout (author renamed binaries); archive layout changed between versions while the manifest was hand-pinned; install dir unwritable after mixed sudo usage; disk full during copy.

Related errors

• 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
• failed to install new version: %w
• failed to ensure create directory %q: %w

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