{"record":{"id":"8171bca822a30eee","repo":"hashicorp/terraform","slug":"failed-to-prepare-working-directory-w","errorCode":null,"errorMessage":"failed to prepare working directory: %w","messagePattern":"failed to prepare working directory: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/command/workdir/dir.go","lineNumber":155,"sourceCode":"\n// TestDataDir returns the path where the receiver keeps settings\n// and artifacts related to terraform tests.\nfunc (d *Dir) TestDataDir() string {\n\treturn filepath.Join(d.dataDir, \"test\")\n}\n\n// ensureDataDir creates the data directory and all of the necessary parent\n// directories that lead to it, if they don't already exist.\n//\n// For directories that already exist ensureDataDir will preserve their\n// permissions, while it'll create any new directories to be owned by the user\n// running Terraform, readable and writable by that user, and readable by\n// all other users, or some approximation of that on non-Unix platforms which\n// have a different permissions model.\nfunc (d *Dir) ensureDataDir() error {\n\terr := os.MkdirAll(d.dataDir, 0755)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to prepare working directory: %w\", err)\n\t}\n\treturn nil\n}\n","sourceCodeStart":137,"sourceCodeEnd":159,"githubUrl":"https://github.com/hashicorp/terraform/blob/c9def3e214014c1188faabfc4a5bde5095139765/internal/command/workdir/dir.go#L137-L159","documentation":"ensureDataDir at dir.go:152 calls os.MkdirAll on the .terraform data directory (overridable via OverrideDataDir / TF_DATA_DIR). This wraps the OS-level error returned when that directory tree cannot be created.","triggerScenarios":"os.MkdirAll(d.dataDir, 0755) at dir.go:153 returns a non-nil error — permission denied, read-only filesystem, an invalid path, ENOSPC, or a non-directory file already exists at that path.","commonSituations":"Running Terraform in a directory without write permission; TF_DATA_DIR pointing somewhere unwritable; a regular file named .terraform blocking the mkdir; a read-only container mount in CI; full disk.","solutions":["Verify write permission on the working directory: 'touch .terraform-test && rm .terraform-test'.","Ensure nothing exists as a regular file at the .terraform path ('ls -la .terraform'); remove it if so.","If TF_DATA_DIR is set, confirm the target path exists, is writable, and is a directory.","Free disk space or remount the filesystem read-write if applicable."],"exampleFix":"// before\n$ terraform init\nError: failed to prepare working directory: mkdir .terraform: permission denied\n\n// after\n$ chmod u+w .\n$ terraform init\n\n// if a file is squatting on the name:\n$ ls -la .terraform\n-rw-r--r-- 1 me me 0 .terraform   # it's a file!\n$ rm .terraform && terraform init","handlingStrategy":"try-catch","validationCode":"// Pre-check writability of the data dir before relying on ensureDataDir.\nfunc isDataDirWritable(p string) bool {\n    fi, err := os.Stat(p)\n    if err == nil && !fi.IsDir() {\n        return false // a file is squatting on the path\n    }\n    probe := filepath.Join(p, \".write-test\")\n    if err := os.MkdirAll(p, 0755); err != nil {\n        return false\n    }\n    _ = os.Remove(probe)\n    return true\n}","typeGuard":"null","tryCatchPattern":"if err := d.ensureDataDir(); err != nil {\n    // err already wraps 'failed to prepare working directory'; surface OS cause\n    if errors.Is(err, os.ErrPermission) { /* guide user to permissions */ }\n}","preventionTips":["Run Terraform with write access to the working directory and TF_DATA_DIR.","Ensure no regular file occupies the .terraform path.","In CI/containers, mount the working dir read-write with adequate free space."],"tags":["terraform","filesystem","permissions","workdir"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T21:17:07.882Z"}