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

Verify the API token is valid and not expired: re-run `terraform login` or regenerate the token in the HCP/TFE UI.

Failed to retrieve workspace %s: %v

Error message

Failed to retrieve workspace %s: %v

What it means

Thrown by StateMgr() when b.client.Workspaces.Read() returns an error that is NOT tfe.ErrResourceNotFound. It means the call to read the workspace from HCP Terraform / Terraform Enterprise failed outright — this is a catch-all for authentication, network, rate-limit, and server-side failures, distinct from the 'workspace missing' case which is handled separately and triggers auto-create.

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 c9def3e214)

Solutions

Verify the API token is valid and not expired: re-run `terraform login` or regenerate the token in the HCP/TFE UI.
Confirm the backend block's `organization` exactly matches the org name in the UI (case-sensitive).
Check that the token's team has at least read access to the organization and the workspace.
If transient, retry the command; for repeated failures inspect the wrapped %v error for the HTTP status (401/403/429/500).
For self-hosted TFE, confirm the `hostname` value and that the host's TLS certificate is trusted by the CLI.

Example fix

// before - expired/missing token
backend "remote" {
  hostname     = "app.terraform.io"
  organization = "acme"
  workspaces { name = "prod" }
}

// after - refresh credentials via `terraform login`,
// or set a fresh token in ~/.terraformrc / credentials helper
$ terraform login app.terraform.io

Defensive patterns

Strategy: validation

Validate before calling

// Validate backend config + token reachability before any state op.
func checkWorkspaceReadable(ctx context.Context, c *tfe.Client, org, name string) error {
    _, err := c.Workspaces.Read(ctx, org, name)
    if err != nil && err != tfe.ErrResourceNotFound {
        return fmt.Errorf("workspace read precheck failed for %s/%s: %w", org, name, err)
    }
    return nil
}

Type guard

func isNotFound(err error) bool {
    return errors.Is(err, tfe.ErrResourceNotFound)
}

Try / catch

ws, err := b.client.Workspaces.Read(ctx, org, name)
if err != nil {
    if errors.Is(err, tfe.ErrResourceNotFound) {
        // not found -> handle create path
    } else if errors.Is(err, context.Canceled) {
        return err
    }
    return fmt.Errorf("Failed to retrieve workspace %s: %w", name, err)
}

Prevention

Store the API token via `terraform login` or a credentials helper so it is fresh and not hard-coded.
Pin and review the `organization` and workspace name/prefix in the backend block in code review.
Run `terraform init` after any backend config change to fail fast on auth/org errors.
Use a least-privilege team token with documented required scopes (read workspaces + state).

When it happens

Trigger: Calling StateMgr() (e.g. `terraform init`, `terraform plan`, any state operation) when Workspaces.Read fails with anything other than 404: a 401/403 (bad/expired token, org access denied), 429 rate limit, 5xx server error, DNS/TLS failure, or an invalid organization name.

Common situations: API token expired or revoked; organization name misspelled in the backend block; the token belongs to a team without read access to the org; transient TFE/HCP outage; corporate proxy intercepting the TLS connection to app.terraform.io; hostname misconfigured for a self-hosted TFE install.

Related errors

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