hashicorp/terraform · error

failed to prepare working directory: %w

Error message

failed to prepare working directory: %w

What it means

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.

Source

Thrown at internal/command/workdir/dir.go:155

// TestDataDir returns the path where the receiver keeps settings
// and artifacts related to terraform tests.
func (d *Dir) TestDataDir() string {
	return filepath.Join(d.dataDir, "test")
}

// ensureDataDir creates the data directory and all of the necessary parent
// directories that lead to it, if they don't already exist.
//
// For directories that already exist ensureDataDir will preserve their
// permissions, while it'll create any new directories to be owned by the user
// running Terraform, readable and writable by that user, and readable by
// all other users, or some approximation of that on non-Unix platforms which
// have a different permissions model.
func (d *Dir) ensureDataDir() error {
	err := os.MkdirAll(d.dataDir, 0755)
	if err != nil {
		return fmt.Errorf("failed to prepare working directory: %w", err)
	}
	return nil
}

View on GitHub (pinned to c9def3e214)

Solutions

1. Verify write permission on the working directory: 'touch .terraform-test && rm .terraform-test'.
2. Ensure nothing exists as a regular file at the .terraform path ('ls -la .terraform'); remove it if so.
3. If TF_DATA_DIR is set, confirm the target path exists, is writable, and is a directory.
4. Free disk space or remount the filesystem read-write if applicable.

Example fix

// before
$ terraform init
Error: failed to prepare working directory: mkdir .terraform: permission denied

// after
$ chmod u+w .
$ terraform init

// if a file is squatting on the name:
$ ls -la .terraform
-rw-r--r-- 1 me me 0 .terraform   # it's a file!
$ rm .terraform && terraform init

// Pre-check writability of the data dir before relying on ensureDataDir.
func isDataDirWritable(p string) bool {
    fi, err := os.Stat(p)
    if err == nil && !fi.IsDir() {
        return false // a file is squatting on the path
    }
    probe := filepath.Join(p, ".write-test")
    if err := os.MkdirAll(p, 0755); err != nil {
        return false
    }
    _ = os.Remove(probe)
    return true
}

null

if err := d.ensureDataDir(); err != nil {
    // err already wraps 'failed to prepare working directory'; surface OS cause
    if errors.Is(err, os.ErrPermission) { /* guide user to permissions */ }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• error deleting workspace %s: %w
• failed to create local modules directory: %s
• failed to write state: %w
• Failed to open script '%s': %v
• failed to retrieve project %s: %v

AI-assisted analysis of hashicorp/terraform@c9def3e214 (2026-08-07). Data as JSON: /api/errors/8171bca822a30eee. Report an issue: GitHub.