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

Check the wrapped error (%v) for HTTP status: 401/403 means re-login or broaden token scope, 5xx/timeout means retry.

Failed to retrieve workspace

Error message

Failed to retrieve workspace %s: %v

What it means

Thrown when Workspaces.Read fails with any error OTHER than tfe.ErrResourceNotFound while resolving a workspace for state operations. The NotFound branch is handled separately (it triggers auto-create), so this error represents a genuine read failure: network, auth, permission, or server error.

Solutions

Check the wrapped error (%v) for HTTP status: 401/403 means re-login or broaden token scope, 5xx/timeout means retry.
Confirm the API token's team has 'Read' access to the workspace.
Retry 'terraform init'/'plan' after confirming TFC/TFE status is green.
If behind a proxy, verify HTTPS_PROXY and TLS inspection settings.

Defensive patterns

Strategy: retry

Validate before calling

// Before operations, sanity-check workspace readability with explicit error handling.
func workspaceReadable(ctx context.Context, client *tfe.Client, org, name string) error {
    _, err := client.Workspaces.Read(ctx, org, name)
    if err != nil && !errors.Is(err, tfe.ErrResourceNotFound) {
        return fmt.Errorf("workspace %s read check failed: %w", name, err)
    }
    return nil
}

Try / catch

// Distinguish NotFound (handled by auto-create) from real failures.
if _, err := b.client.Workspaces.Read(ctx, org, name); err != nil {
    if errors.Is(err, tfe.ErrResourceNotFound) { /* create path */ }
    if errors.Is(err, context.Canceled) { return err }
    // transient (5xx/429/timeout) -> retry with backoff; auth (401/403) -> re-login

Prevention

Pre-create workspaces in CI rather than relying on auto-create, so read failures are clearly auth/network.
Grant the token's team at least 'Read' on all target workspaces.
Run operations through retry-with-backoff for transient transport errors.

When it happens

Trigger: b.client.Workspaces.Read(ctx, org, name) returns a non-nil, non-NotFound error. Typical causes: 401/403 (token not authorized for the workspace), 5xx from TFE, request timeout, DNS/connectivity failure, or rate limiting.

Common situations: Token lacks 'Read Workspace' permission on the target workspace; transient TFE outage or maintenance window; corporate proxy intercepting the connection; rate-limited by TFC; expired token mid-session.

Related errors

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

Appendix: source

Thrown at internal/backend/remote/backend.go:671

	var diags tfdiags.Diagnostics
	if b.workspace == "" && name == backend.DefaultStateName {
		return nil, diags.Append(backend.ErrDefaultWorkspaceNotSupported)
	}
	if b.prefix == "" && name != backend.DefaultStateName {
		return nil, diags.Append(backend.ErrWorkspacesNotSupported)
	}

	// Configure the remote workspace name.
	switch {
	case name == backend.DefaultStateName:
		name = b.workspace
	case b.prefix != "" && !strings.HasPrefix(name, b.prefix):
		name = b.prefix + name
	}

	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 err == tfe.ErrResourceNotFound {
		options := tfe.WorkspaceCreateOptions{
			Name: tfe.String(name),
		}

		// We only set the Terraform Version for the new workspace if this is
		// a release candidate or a final release.
		if tfversion.Prerelease == "" || strings.HasPrefix(tfversion.Prerelease, "rc") {
			options.TerraformVersion = tfe.String(tfversion.String())
		}

		workspace, err = b.client.Workspaces.Create(context.Background(), b.organization, options)
		if err != nil {
			return nil, diags.Append(fmt.Errorf("Error creating workspace %s: %v", name, err))
		}
	}

View on GitHub (pinned to d32a084675)