hashicorp/terraform · error

failed to retrieve workspace

Error message

failed to retrieve workspace %s: %v

What it means

During DeleteWorkspace, the backend reads the workspace from the TFE/HCP API. If the read fails with any error other than tfe.ErrResourceNotFound (which is treated as success — the workspace doesn't exist so deletion is a no-op), the error is wrapped and returned. This prevents attempting to delete a workspace whose state cannot be retrieved.

Solutions

1. Verify the workspace name is correct and the token has read access to it.
2. Retry the operation if the error was transient (network blip, rate limit).
3. Check that the organization name is correct in the cloud configuration.
4. Use the HCP Terraform / TFE UI to verify the workspace exists and the token has access.

// Before deleting, verify workspace is accessible
_, err := b.client.Workspaces.Read(ctx, b.Organization, name)
if err != nil && err != tfe.ErrResourceNotFound {
    return fmt.Errorf("cannot access workspace %s: %w", name, err)
}

// Retry workspace read before delete
for i := 0; i < 3; i++ {
    workspace, err := b.client.Workspaces.Read(ctx, b.Organization, name)
    if err == nil {
        // proceed with delete
        break
    }
    if err == tfe.ErrResourceNotFound {
        return nil // already gone
    }
    if i == 2 {
        return diags.Append(fmt.Errorf("failed to retrieve workspace %s: %v", name, err))
    }
    time.Sleep(time.Duration(1<<i) * time.Second)
}

When it happens

Trigger: Calling b.client.Workspaces.Read at backend.go:710 during a workspace delete operation returns a non-nil, non-404 error. Causes include API authentication failures, permission errors, rate limiting, server-side errors, or network connectivity issues.

Common situations: The API token lacks permission to read the target workspace. Transient API errors during `terraform workspace delete`. Network issues between Terraform and the HCP Terraform / TFE host. The workspace name contains special characters or is incorrectly specified.

Related errors

• Failed to retrieve workspace
• Attempted to find configured project
• failed to retrieve project
• organization at host not found. Please ensure that the…
• a network issue prevented cloud configuration;

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

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