hashicorp/terraform · error

Error retrieving state: %v

Error message

Error retrieving state: %v

What it means

Emitted by remoteClient.Get (backend_state.go:52-63) when StateVersions.ReadCurrent fails for any reason other than tfe.ErrResourceNotFound. ReadCurrent queries the TFC/TFE API for the workspace's current state version; on success it returns the version metadata used to fetch the actual state bytes. A non-404 failure here means the API call itself broke, so the underlying cause is surfaced verbatim via %v.

Source

Thrown at internal/backend/remote/backend_state.go:62

func (e errorUnlockFailed) Error() string {
	return e.innerError.Error()
}

var _ Fatal = errorUnlockFailed{}

// Get the remote state.
func (r *remoteClient) Get() (*remote.Payload, tfdiags.Diagnostics) {
	var diags tfdiags.Diagnostics
	ctx := context.Background()

	sv, err := r.client.StateVersions.ReadCurrent(ctx, r.workspace.ID)
	if err != nil {
		if err == tfe.ErrResourceNotFound {
			// If no state exists, then return nil.
			return nil, nil
		}
		return nil, diags.Append(fmt.Errorf("Error retrieving state: %v", err))
	}

	state, err := r.client.StateVersions.Download(ctx, sv.DownloadURL)
	if err != nil {
		return nil, diags.Append(fmt.Errorf("Error downloading state: %v", err))
	}

	// If the state is empty, then return nil.
	if len(state) == 0 {
		return nil, nil
	}

	// Get the MD5 checksum of the state.
	sum := md5.Sum(state)

	return &remote.Payload{
		Data: state,
		MD5:  sum[:],

View on GitHub (pinned to c9def3e214)

Solutions

1. Re-authenticate: run `terraform login` (or set TF_TOKEN_<host> / TFE_TOKEN) to refresh a valid API token.
2. Verify the workspace exists and the token's team/user has read access in the TFC/TFE UI.
3. Check connectivity to the TFC/TFE host (curl, DNS) and any required proxy env vars (HTTPS_PROXY).
4. Retry the command after confirming TFC status page shows no incident; transient 5xx often resolve on retry.

Example fix

// before: token expired
$ terraform plan
Error: Error retrieving state: resource not found / unauthorized

// after: refresh credentials and confirm workspace
$ terraform login app.terraform.io
$ terraform workspace show   # confirm correct workspace selected
$ terraform plan

// Validate reachability and credentials before issuing state operations.
ctx := context.Background()
if _, err := b.client.Organizations.Read(ctx, r.organization); err != nil {
    return fmt.Errorf("preflight: cannot reach TFC org %q: %w", r.organization, err)
}

// Wrap ReadCurrent in a bounded retry for transient failures; surface fatal ones.
var sv *tfe.StateVersion
err := RetryBackoff(ctx, func() error {
    var e error
    sv, e = b.client.StateVersions.ReadCurrent(ctx, r.workspace.ID)
    if e == tfe.ErrResourceNotFound { return nil }
    return e
})
if err != nil { return nil, fmt.Errorf("Error retrieving state: %v", err) }

When it happens

Trigger: Calling terraform with a configured remote/cloud backend while the TFC/TFE StateVersions.ReadCurrent API call fails: expired/invalid API token, 403 forbidden, 5xx from TFC, network interruption, DNS failure, or a workspace ID pointing to a deleted workspace that returns something other than a clean 404.

Common situations: Terraform token expired or revoked; user lacks read permission on the workspace; TFC outage or maintenance; corporate proxy/firewall blocking app.terraform.io; stale local backend config referencing a renamed organization/workspace; clock skew causing TLS failures.

Related errors

• Error downloading state: %v
• Failed to upload state to %v: %v
• error uploading state: %v
• operation timed out
• storage.NewClient() failed: %v

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