{"record":{"id":"e2d324124adbc22e","repo":"hashicorp/terraform","slug":"failed-to-initialize-stacksplugin-cache-directory","errorCode":null,"errorMessage":"failed to initialize stacksplugin cache directory: %w","messagePattern":"failed to initialize stacksplugin cache directory: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/command/stacks.go","lineNumber":403,"sourceCode":"\t\t\tpluginPath = defaultPluginPath\n\t\t} else {\n\t\t\tlog.Printf(\"[TRACE] Failed to check the stacksplugin cache path store at '%s', using default '%s'\", cacheStorePath, defaultPluginPath)\n\t\t\t// Use the default plugin cache path if there was an error checking the file\n\t\t\tpluginPath = defaultPluginPath\n\t\t}\n\t} else {\n\t\tdata, err := os.ReadFile(cacheStorePath)\n\t\tif err != nil {\n\t\t\treturn \"\", fmt.Errorf(\"failed to read stacks plugin stored path file: %w\", err)\n\t\t}\n\t\tpluginPath = string(data)\n\t}\n\n\tif info, err := os.Stat(pluginPath); err != nil || !info.IsDir() {\n\t\tlog.Printf(\"[TRACE] initialized stacksplugin cache directory at %q\", pluginPath)\n\t\terr = os.MkdirAll(pluginPath, 0755)\n\t\tif err != nil {\n\t\t\treturn \"\", fmt.Errorf(\"failed to initialize stacksplugin cache directory: %w\", err)\n\t\t}\n\t} else {\n\t\tlog.Printf(\"[TRACE] stacksplugin cache directory found at %q\", pluginPath)\n\t}\n\n\treturn pluginPath, nil\n}\n\nfunc (c *StacksCommand) storeStacksPluginPath(pluginCachePath string) error {\n\tf, err := os.Create(path.Join(c.WorkingDir.DataDir(), \".stackspluginpath\"))\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to create stacks plugin stored path file: %w\", err)\n\t}\n\tdefer f.Close()\n\tf.WriteString(pluginCachePath)\n\n\treturn nil\n}","sourceCodeStart":385,"sourceCodeEnd":421,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/command/stacks.go#L385-L421","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the wrapped PathError to see which path component failed and why.","Edit or delete `.stackspluginpath` so the default writable cache path is used.","Ensure the parent directory exists and is writable: `mkdir -p <parent> && chmod 755 <parent>`.","Free disk space or remount the volume read-write if applicable."],"exampleFix":"# before: .stackspluginpath points at /opt/terraform-plugins\n sudo terraform stacks up\n\n# after\n rm .terraform/.stackspluginpath\n terraform stacks up","handlingStrategy":"validation","validationCode":"// Verify the plugin path is writable before MkdirAll.\nif err := os.MkdirAll(filepath.Dir(pluginPath), 0755); err != nil {\n    return \"\", fmt.Errorf(\"plugin path parent not writable: %w\", err)\n}\nif info, err := os.Stat(pluginPath); err == nil && !info.IsDir() {\n    return \"\", fmt.Errorf(\"plugin path %s exists and is not a directory\", pluginPath)\n}","typeGuard":null,"tryCatchPattern":"if err := os.MkdirAll(pluginPath, 0755); err != nil {\n    // Surface the underlying PathError so the user can fix permissions/disk.\n    var pathErr *os.PathError\n    if errors.As(err, &pathErr) {\n        return \"\", fmt.Errorf(\"cannot create plugin cache at %s (%s): %w\", pathErr.Path, pathErr.Op, err)\n    }\n    return \"\", fmt.Errorf(\"failed to initialize stacksplugin cache directory: %w\", err)\n}","preventionTips":["Do not edit `.stackspluginpath` to point at system directories.","Use a writable TF_DATA_DIR on read-only filesystems.","Monitor disk usage on runners; MkdirAll fails on ENOSPC.","In containers, mount the cache dir as a writable volume."],"tags":["terraform","stacks","plugin","filesystem","permissions","disk"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}