What causes "failed to retrieve workspace %s: %v" in hashicorp/terraform?

Ensure the token's team has admin/delete permission on the workspace.

failed to retrieve workspace %s: %v

Error message

failed to retrieve workspace %s: %v

What it means

Returned in backend DeleteWorkspace at backend.go:716 when b.client.Workspaces.Read returns a non-ErrResourceNotFound error during terraform workspace delete. NotFound is treated as success (idempotent delete); any other error (permissions, API failure, network) is reported here with %s=workspace name and %v=error.

Source

Thrown at internal/cloud/backend.go:716

// DeleteWorkspace implements backend.Backend (which is embedded in backendrun.OperationsBackend).
func (b *Cloud) DeleteWorkspace(name string, force bool) tfdiags.Diagnostics {
	var diags tfdiags.Diagnostics

	if name == backend.DefaultStateName {
		return diags.Append(backend.ErrDefaultWorkspaceNotSupported)
	}

	if b.WorkspaceMapping.Strategy() == WorkspaceNameStrategy {
		return diags.Append(backend.ErrWorkspacesNotSupported)
	}

	workspace, err := b.client.Workspaces.Read(context.Background(), b.Organization, name)
	if err == tfe.ErrResourceNotFound {
		return nil // If the workspace does not exist, succeed
	}

	if err != nil {
		return diags.Append(fmt.Errorf("failed to retrieve workspace %s: %v", name, err))
	}

	// Configure the remote workspace name.
	State := &State{tfeClient: b.client, organization: b.Organization, workspace: workspace, enableIntermediateSnapshots: false}
	return diags.Append(State.Delete(force))
}

// StateMgr implements backend.Backend (which is embedded in backendrun.OperationsBackend).
func (b *Cloud) StateMgr(name string) (statemgr.Full, tfdiags.Diagnostics) {
	var diags tfdiags.Diagnostics

	var remoteTFVersion string

	if name == backend.DefaultStateName {
		return nil, diags.Append(backend.ErrDefaultWorkspaceNotSupported)
	}

	if b.WorkspaceMapping.Strategy() == WorkspaceNameStrategy && name != b.WorkspaceMapping.Name {

View on GitHub (pinned to c9def3e214)

Solutions

Ensure the token's team has admin/delete permission on the workspace.
Retry after transient API errors; verify HCP/TFE status page.
Confirm the workspace name is correct and not locked by a run.

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check workspace existence for delete to give a clearer error.
if _, err := b.client.Workspaces.Read(ctx, org, name); err != nil && !errors.Is(err, tfe.ErrResourceNotFound) {
    return fmt.Errorf("cannot verify workspace %s: %w", name, err)
}

Type guard

if errors.Is(err, tfe.ErrResourceNotFound) { return nil /* idempotent */ }

Try / catch

ws, err := b.client.Workspaces.Read(ctx, org, name)
if errors.Is(err, tfe.ErrResourceNotFound) {
    return nil // already gone
} else if err != nil {
    return fmt.Errorf("failed to retrieve workspace %s: %v", name, err)
}

Prevention

Grant workspace admin/delete permission to the token's team.
Ensure the workspace is not locked by an active run before deleting.

When it happens

Trigger: terraform workspace delete <name> against a cloud backend; the workspace Read call fails with an error other than 404.

Common situations: Token lacks workspace read/delete permission; API outage; rate limiting; workspace name typo that surfaces as a permission or transport error rather than 404.

Related errors

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