{"record":{"id":"6dd0f416e05fe9f1","repo":"hashicorp/terraform","slug":"failed-to-initialize-cloudplugin-cache-directory","errorCode":null,"errorMessage":"failed to initialize cloudplugin cache directory: %w","messagePattern":"failed to initialize cloudplugin cache directory: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/command/cloud.go","lineNumber":256,"sourceCode":"\t\tdiags = diags.Append(tfdiags.Sourceless(\n\t\t\ttfdiags.Warning,\n\t\t\t\"Cloud plugin development overrides are in effect\",\n\t\t\tdetailMsg,\n\t\t))\n\t}\n\tlog.Printf(\"[TRACE] plugin %q binary located at %q%s\", version.ProductVersion, version.Path, cacheTraceMsg)\n\tc.pluginBinary = version.Path\n\treturn diags\n}\n\nfunc (c *CloudCommand) initPackagesCache() (string, error) {\n\tpackagesPath := path.Join(c.WorkingDir.DataDir(), CloudPluginDataDir)\n\n\tif info, err := os.Stat(packagesPath); err != nil || !info.IsDir() {\n\t\tlog.Printf(\"[TRACE] initialized cloudplugin cache directory at %q\", packagesPath)\n\t\terr = os.MkdirAll(packagesPath, 0755)\n\t\tif err != nil {\n\t\t\treturn \"\", fmt.Errorf(\"failed to initialize cloudplugin cache directory: %w\", err)\n\t\t}\n\t} else {\n\t\tlog.Printf(\"[TRACE] cloudplugin cache directory found at %q\", packagesPath)\n\t}\n\n\treturn packagesPath, nil\n}\n\n// Run runs the cloud command with the given arguments.\nfunc (c *CloudCommand) Run(args []string) int {\n\targs = c.Meta.process(args)\n\treturn c.realRun(args, c.Meta.Streams.Stdout.File, c.Meta.Streams.Stderr.File)\n}\n\n// Help returns help text for the cloud command.\nfunc (c *CloudCommand) Help() string {\n\thelpText := new(bytes.Buffer)\n\tif exitCode := c.realRun([]string{}, helpText, io.Discard); exitCode != 0 {","sourceCodeStart":238,"sourceCodeEnd":274,"githubUrl":"https://github.com/hashicorp/terraform/blob/c9def3e214014c1188faabfc4a5bde5095139765/internal/command/cloud.go#L238-L274","documentation":"Returned by CloudCommand.initPackagesCache (cloud.go:249) when os.MkdirAll fails to create the cloudplugin cache directory under the data dir (TF_DATA_DIR, default .terraform). This cache holds the downloaded terraform-cloudplugin binary; without it, the `terraform cloud` / packages-based cloud subcommands cannot stage the plugin. The error is wrapped with %w so callers can inspect the underlying os.PathError.","triggerScenarios":"os.MkdirAll(packagesPath, 0755) fails: TF_DATA_DIR points to a read-only or non-existent parent that cannot be created, permission denied on a path component, disk full, or a file (not directory) already exists at packagesPath blocking MkdirAll.","commonSituations":"TF_DATA_DIR set to a read-only location in CI; a previous run created a file at the cache path; the data dir is on a network share that refuses directory creation; running as a user without write permission to the working directory's .terraform; container with read-only root filesystem and no writable volume for the data dir.","solutions":["Verify TF_DATA_DIR (or the working directory's .terraform) is writable: `ls -ld .terraform` and `mkdir -p .terraform/plugins && rm -d .terraform/plugins`.","If a regular file occupies the cache path, remove it: `ls -la .terraform/cloudplugin` and `rm` it if it is a file.","Unset or repoint TF_DATA_DIR to a writable directory and retry.","In read-only containers, mount a writable volume at the data dir or set TF_DATA_DIR=/tmp/tf-data.","Free disk space / fix permissions on the parent directory."],"exampleFix":"# before\n$ terraform cloud\nfailed to initialize cloudplugin cache directory: mkdir .terraform/cloudplugin: read-only file system\n\n# after: mount a writable volume / repoint data dir\n$ export TF_DATA_DIR=/tmp/tf-data\n$ terraform cloud","handlingStrategy":"validation","validationCode":"// Validate the cloudplugin cache path before initialization\npackagesPath := filepath.Join(dataDir, \"cloudplugin\")\nif info, err := os.Stat(packagesPath); err == nil && !info.IsDir() {\n    return fmt.Errorf(\"%s exists and is not a directory; remove it\", packagesPath)\n}\nif err := os.MkdirAll(filepath.Dir(packagesPath), 0755); err != nil {\n    return fmt.Errorf(\"cannot create parent of cloudplugin cache: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"// On cache init failure, fall back to disabling the cloud subcommand rather than crashing the whole CLI.\nif _, err := c.initPackagesCache(); err != nil {\n    log.Printf(\"warning: cloudplugin cache unavailable (%v); `terraform cloud` will be disabled\", err)\n    c.cloudDisabled = true\n}","preventionTips":["Pin TF_DATA_DIR to a writable location in containers/CI.","Pre-create the data directory and the cloudplugin subdir during provisioning.","Read-only root filesystems must mount a writable volume for TF_DATA_DIR.","Document that the cloudplugin cache must be a directory, not a file."],"tags":["cloud","filesystem","permissions","plugin-cache","configuration"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T21:17:07.882Z"}