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

Refresh the API token: run `terraform login ` or update TF_TOKEN_ .

Failed to retrieve workspace

Error message

Failed to retrieve workspace %s: %v

What it means

During StateMgr initialization, the backend reads the workspace from the TFE/HCP API. If the read fails with any error other than tfe.ErrResourceNotFound (which triggers workspace creation logic), the error is wrapped with this message and returned, preventing state manager initialization.

Solutions

Refresh the API token: run `terraform login <hostname>` or update TF_TOKEN_<hostname>.
Verify the token has read/create permissions for workspaces in the organization.
Retry after a brief wait if the error is transient.
Check that the workspace name or tags mapping resolves to a valid workspace.

Defensive patterns

Strategy: retry

Validate before calling

// Before StateMgr init, verify workspace accessibility
_, 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)
}

Try / catch

// Retry workspace read during StateMgr init
var workspace *tfe.Workspace
for i := 0; i < 3; i++ {
    workspace, err = b.client.Workspaces.Read(ctx, b.Organization, name)
    if err == nil || err == tfe.ErrResourceNotFound {
        break
    }
    if i == 2 {
        return nil, diags.Append(fmt.Errorf("Failed to retrieve workspace %s: %v", name, err))
    }
    time.Sleep(time.Duration(1<<i) * time.Second)
}

Prevention

Run 'terraform login <hostname>' to ensure a valid token before plan/apply.
Verify the token has workspace read and create permissions.
Retry transient errors; HCP Terraform / TFE may rate-limit or have temporary outages.
Confirm the workspace name or tags strategy resolves to valid workspaces.

When it happens

Trigger: Calling b.client.Workspaces.Read at backend.go:738 during StateMgr setup returns a non-nil, non-404 error. This happens during any Terraform operation (plan, apply, init) that needs a state manager for a cloud-backed workspace. The API call fails due to auth, permissions, rate limiting, or server errors.

Common situations: Running 'terraform plan' or 'terraform apply' against a cloud backend where the API token is expired or revoked. The token has insufficient permissions for the workspace. Transient network or server errors during state manager setup. Rate limiting from too many concurrent Terraform runs.

Related errors

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

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