hashicorp/terraform · error

failed to prepare working directory

Error message

failed to prepare working directory: %w

What it means

Dir.ensureDataDir wraps a failed os.MkdirAll on the working directory's data directory (.terraform). The %w carries the OS-level error. ensureDataDir is called during normal working-directory setup, so this surfaces as a failure to prep the workspace.

Solutions

1. Check the wrapped error for EACCES / ENOSPC / EROFS and address that specific cause.
2. Ensure the user running Terraform owns (or can write) the workspace and all parents.
3. Remove any regular file named `.terraform` blocking the directory creation.
4. Free inodes/space on the target filesystem.

Example fix

# before — running in read-only mount
terraform init  # -> failed to prepare working directory: ...

# after — run from a writable workspace
cd ~/work/myenv && terraform init

// pre-flight: confirm we can write to the workspace
testPath := filepath.Join(d.dataDir, ".write-test")
if err := os.WriteFile(filepath.Dir(d.dataDir)+"/.write-probe", []byte("x"), 0644); err != nil {
    return fmt.Errorf("workspace not writable: %w", err)
}
_ = os.Remove(testPath)

if err := d.ensureDataDir(); err != nil {
    if errors.Is(err, os.ErrPermission) { return fmt.Errorf("permission denied creating .terraform: %w", err) }
    if errors.Is(err, os.ErrNotExist) { return fmt.Errorf("parent directory missing: %w", err) }
    return err
}

When it happens

Trigger: Terraform cannot create .terraform (or its parents): permission denied on a parent, read-only filesystem, path-too-long, disk full, or an existing non-directory file at the dataDir path.

Common situations: Running in a CI step with a read-only workspace, restricted container mount, NFS permission mismatch, a file named `.terraform` left in the way, or filesystem out of space.

Related errors

• Failed to set new workspace
• cannot create temporary file to update credentials
• Cannot read directory
• cannot read
• cannot search

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

Appendix: 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 d32a084675)