hashicorp/terraform · error

failed to initialize stacksplugin cache directory

Error message

failed to initialize stacksplugin cache directory: %w

What it means

Thrown by the stacks plugin path loader when os.MkdirAll(pluginPath, 0755) returns an error. The target pluginPath (either from .stackspluginpath or the default) does not exist as a directory and cannot be created. The error wraps the underlying os.PathError (mkdir, permission denied, no space, read-only filesystem).

Solutions

1. Inspect the wrapped PathError to see which path component failed and why.
2. Edit or delete `.stackspluginpath` so the default writable cache path is used.
3. Ensure the parent directory exists and is writable: `mkdir -p <parent> && chmod 755 <parent>`.
4. Free disk space or remount the volume read-write if applicable.

Example fix

# before: .stackspluginpath points at /opt/terraform-plugins
 sudo terraform stacks up

# after
 rm .terraform/.stackspluginpath
 terraform stacks up

// Verify the plugin path is writable before MkdirAll.
if err := os.MkdirAll(filepath.Dir(pluginPath), 0755); err != nil {
    return "", fmt.Errorf("plugin path parent not writable: %w", err)
}
if info, err := os.Stat(pluginPath); err == nil && !info.IsDir() {
    return "", fmt.Errorf("plugin path %s exists and is not a directory", pluginPath)
}

if err := os.MkdirAll(pluginPath, 0755); err != nil {
    // Surface the underlying PathError so the user can fix permissions/disk.
    var pathErr *os.PathError
    if errors.As(err, &pathErr) {
        return "", fmt.Errorf("cannot create plugin cache at %s (%s): %w", pathErr.Path, pathErr.Op, err)
    }
    return "", fmt.Errorf("failed to initialize stacksplugin cache directory: %w", err)
}

When it happens

Trigger: pluginPath resolves to a location the user cannot write: `/usr/lib/...` without root, a read-only mount, a parent component is a file not a directory, ENOSPC, or the configured path string contains characters the OS rejects.

Common situations: Default cache path on a read-only container layer; `.stackspluginpath` manually edited to point at an unwritable location; CI runner out of disk; restricted Podium/SELinux policy; running as a uid that has no home dir.

Related errors

• failed to create stacks plugin stored path file
• failed to read stacks plugin stored path file
• error loading plugin path
• error loading plugin path
• a network issue prevented cloud configuration;

AI-assisted analysis of hashicorp/terraform@d32a084675 (2026-08-11). Data as JSON: /api/errors/e2d324124adbc22e. Report an issue: GitHub.

Appendix: source

Thrown at internal/command/stacks.go:403

			pluginPath = defaultPluginPath
		} else {
			log.Printf("[TRACE] Failed to check the stacksplugin cache path store at '%s', using default '%s'", cacheStorePath, defaultPluginPath)
			// Use the default plugin cache path if there was an error checking the file
			pluginPath = defaultPluginPath
		}
	} else {
		data, err := os.ReadFile(cacheStorePath)
		if err != nil {
			return "", fmt.Errorf("failed to read stacks plugin stored path file: %w", err)
		}
		pluginPath = string(data)
	}

	if info, err := os.Stat(pluginPath); err != nil || !info.IsDir() {
		log.Printf("[TRACE] initialized stacksplugin cache directory at %q", pluginPath)
		err = os.MkdirAll(pluginPath, 0755)
		if err != nil {
			return "", fmt.Errorf("failed to initialize stacksplugin cache directory: %w", err)
		}
	} else {
		log.Printf("[TRACE] stacksplugin cache directory found at %q", pluginPath)
	}

	return pluginPath, nil
}

func (c *StacksCommand) storeStacksPluginPath(pluginCachePath string) error {
	f, err := os.Create(path.Join(c.WorkingDir.DataDir(), ".stackspluginpath"))
	if err != nil {
		return fmt.Errorf("failed to create stacks plugin stored path file: %w", err)
	}
	defer f.Close()
	f.WriteString(pluginCachePath)

	return nil
}

View on GitHub (pinned to d32a084675)