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

Grant the token's team read access to the workspace (or the whole org).

Failed to retrieve workspace %s: %v

Error message

Failed to retrieve workspace %s: %v

What it means

Returned in backend StateMgr at backend.go:740 when b.client.Workspaces.Read returns any error other than tfe.ErrResourceNotFound while resolving the state manager for a workspace (i.e. during plan/apply). Note the capital 'F' (Failed) distinguishing it from 475. ErrResourceNotFound is allowed through so the backend can auto-create the workspace; all other errors are fatal to state setup.

Source

Thrown at internal/cloud/backend.go:740

}

// 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 {
		return nil, diags.Append(backend.ErrWorkspacesNotSupported)
	}

	workspace, err := b.client.Workspaces.Read(context.Background(), b.Organization, name)
	if err != nil && err != tfe.ErrResourceNotFound {
		return nil, diags.Append(fmt.Errorf("Failed to retrieve workspace %s: %v", name, err))
	}
	if workspace != nil {
		remoteTFVersion = workspace.TerraformVersion
	}

	var configuredProject *tfe.Project

	// Attempt to find project if configured
	if b.WorkspaceMapping.Project != "" {
		listOpts := &tfe.ProjectListOptions{
			Name: b.WorkspaceMapping.Project,
		}
		projects, err := b.client.Projects.List(context.Background(), b.Organization, listOpts)
		if err != nil && err != tfe.ErrResourceNotFound {
			// This is a failure to make an API request, fail to initialize
			return nil, diags.Append(fmt.Errorf("Attempted to find configured project %s but was unable to.", b.WorkspaceMapping.Project))
		}
		for _, p := range projects.Items {

View on GitHub (pinned to c9def3e214)

Solutions

Grant the token's team read access to the workspace (or the whole org).
Retry on transient 5xx/rate-limit; check status.cloud.hashicorp.com.
If workspace auto-create is disabled, create the workspace first in the UI.

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight workspace access before plan to surface auth issues early.
if _, err := b.client.Workspaces.Read(ctx, org, name); err != nil && !errors.Is(err, tfe.ErrResourceNotFound) {
    return fmt.Errorf("token cannot read workspace %s: %w", name, err)
}

Type guard

if errors.Is(err, tfe.ErrResourceNotFound) { /* allow auto-create path */ }

Try / catch

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

Prevention

Grant workspace read to the token's team for plan/apply.
Retry transient 5xx/rate-limit errors; check the HCP status page.

When it happens

Trigger: terraform plan/apply with a cloud backend; Workspaces.Read for the target workspace returns 401/403/500/rate-limit/network instead of 404.

Common situations: Token lacks read on the workspace; concurrent run locking API; TFE/HCP 5xx; proxy/rate-limit during a CI plan; workspace auto-create disabled and the workspace genuinely missing but surfaced as a permission error.

Related errors

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