hasura/graphql-engine · error

could not create staging dir %q: %w

Error message

could not create staging dir %q: %w

What it means

installPlugin() downloads the plugin into a staging directory under the CLI's download path; before downloading it creates that directory with os.MkdirAll. Any error creating the staging dir aborts the install immediately with this message naming the offending path.

Source

Thrown at cli/plugins/plugins.go:292

	return nil
}

func (c *Config) installPlugin(plugin Plugin, platform Platform) error {
	var op errors.Op = "plugins.Config.installPlugin"

	downloadStagingDir := filepath.Join(c.Paths.DownloadPath(), plugin.Name)
	installDir := c.Paths.PluginVersionInstallPath(plugin.Name, plugin.Version)
	binDir := c.Paths.BinPath()

	// check if install dir already exists
	_, err := os.Stat(installDir)
	if err != nil {
		// Download and extract
		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 {

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check the exact path named in the error message with ls -la; if a file exists where a directory is expected, remove it
2. Fix ownership/permissions of the download path and its parents so the current user can create directories
3. Free disk space / raise quota if the mkdir fails with ENOSPC
4. Ensure the plugins data/download directory is on a writable filesystem (relevant in containers and CI)

Example fix

# before: download path is a regular file
$ ls -la ~/.cli/downloads
-rw-r--r-- 1 user user 0 downloads
$ rm ~/.cli/downloads
# after: install recreates it as a directory and succeeds

staging := filepath.Join(cfg.Paths.DownloadPath(), plugin.Name)
if fi, err := os.Stat(staging); err == nil && !fi.IsDir() {
	_ = os.Remove(staging) // clear a stray file blocking MkdirAll
}
if err := os.MkdirAll(filepath.Dir(staging), 0o755); err != nil {
	// repair permissions before calling Install
}

if err := cfg.Install(plugin); err != nil && strings.Contains(err.Error(), "could not create staging dir") {
	// fix ownership/permissions on the named path, remove conflicting file, retry
}

When it happens

Trigger: MkdirAll(DownloadPath()/plugin.Name) failing: the download path exists as a regular file, a parent directory lacks write permission, disk quota exceeded, or a read-only filesystem.

Common situations: Plugins download cache dir owned by root from earlier sudo use; home directory over quota; the download path was accidentally created as a file; container/CI environments with read-only volumes for the config dir.

Related errors

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

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