What causes "error deleting workspace %s: %w" in hashicorp/terraform?

Check the wrapped error for the OS cause (permission denied, busy, etc.) and fix ownership/permissions on the state directory.

hashicorp/terraform · error

error deleting workspace %s: %w

Error message

error deleting workspace %s: %w

What it means

Returned by Local.DeleteWorkspace when os.RemoveAll fails to remove the workspace's state directory on disk. The workspace name is included; the wrapped error is the underlying OS/filesystem error. The 'default' workspace and empty names are rejected earlier, so this is purely a filesystem failure.

Source

Thrown at internal/backend/local/backend.go:254

	var diags tfdiags.Diagnostics

	// If we have a backend handling state, defer to that.
	if b.Backend != nil {
		return b.Backend.DeleteWorkspace(name, force)
	}

	if name == "" {
		return diags.Append(errors.New("empty state name"))
	}

	if name == backend.DefaultStateName {
		return diags.Append(errors.New("cannot delete default state"))
	}

	delete(b.states, name)
	err := os.RemoveAll(filepath.Join(b.stateWorkspaceDir(), name))
	if err != nil {
		return diags.Append(fmt.Errorf("error deleting workspace %s: %w", name, err))
	}

	return diags
}

func (b *Local) StateMgr(name string) (statemgr.Full, tfdiags.Diagnostics) {
	var diags tfdiags.Diagnostics

	// If we have a backend handling state, delegate to that.
	if b.Backend != nil {
		return b.Backend.StateMgr(name)
	}

	if s, ok := b.states[name]; ok {
		return s, diags
	}

	if err := b.createState(name); err != nil {

View on GitHub (pinned to c9def3e214)

Solutions

Check the wrapped error for the OS cause (permission denied, busy, etc.) and fix ownership/permissions on the state directory.
Close other processes holding handles to the workspace files, then retry the delete.
If the directory is already gone, verify with terraform workspace list; manually clean the entry if state is inconsistent.

Defensive patterns

Strategy: try-catch

Try / catch

diags := b.DeleteWorkspace(name, force)
if diags.HasErrors() {
    // inspect underlying cause; os.RemoveAll errors are in the diagnostics
    return diags.Err()
}

Prevention

Run terraform as a user that owns the state directory tree.
Avoid manually editing/deleting workspace directories under Terraform's state path.
On Windows/shared filesystems, ensure no process holds open handles before deleting workspaces.

When it happens

Trigger: Calling terraform workspace delete <name> (or the backend DeleteWorkspace API) when the on-disk workspace directory under the state workspace dir cannot be removed — e.g. permission denied, path is a mount, file busy, or the directory was already removed/modified externally.

Common situations: Filesystem permission mismatch (state dir owned by root, terraform run as non-root); NFS/mount busy handles; antivirus or another process holding file handles on Windows; someone manually deleting the workspace dir out from under Terraform.

Related errors

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