{"record":{"id":"3bfcc6bd56a12f72","repo":"hashicorp/terraform","slug":"error-retrieving-state-v","errorCode":null,"errorMessage":"Error retrieving state: %v","messagePattern":"Error retrieving state: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/backend/remote/backend_state.go","lineNumber":62,"sourceCode":"\nfunc (e errorUnlockFailed) Error() string {\n\treturn e.innerError.Error()\n}\n\nvar _ Fatal = errorUnlockFailed{}\n\n// Get the remote state.\nfunc (r *remoteClient) Get() (*remote.Payload, tfdiags.Diagnostics) {\n\tvar diags tfdiags.Diagnostics\n\tctx := context.Background()\n\n\tsv, err := r.client.StateVersions.ReadCurrent(ctx, r.workspace.ID)\n\tif err != nil {\n\t\tif err == tfe.ErrResourceNotFound {\n\t\t\t// If no state exists, then return nil.\n\t\t\treturn nil, nil\n\t\t}\n\t\treturn nil, diags.Append(fmt.Errorf(\"Error retrieving state: %v\", err))\n\t}\n\n\tstate, err := r.client.StateVersions.Download(ctx, sv.DownloadURL)\n\tif err != nil {\n\t\treturn nil, diags.Append(fmt.Errorf(\"Error downloading state: %v\", err))\n\t}\n\n\t// If the state is empty, then return nil.\n\tif len(state) == 0 {\n\t\treturn nil, nil\n\t}\n\n\t// Get the MD5 checksum of the state.\n\tsum := md5.Sum(state)\n\n\treturn &remote.Payload{\n\t\tData: state,\n\t\tMD5:  sum[:],","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/hashicorp/terraform/blob/c9def3e214014c1188faabfc4a5bde5095139765/internal/backend/remote/backend_state.go#L44-L80","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Re-authenticate: run `terraform login` (or set TF_TOKEN_<host> / TFE_TOKEN) to refresh a valid API token.","Verify the workspace exists and the token's team/user has read access in the TFC/TFE UI.","Check connectivity to the TFC/TFE host (curl, DNS) and any required proxy env vars (HTTPS_PROXY).","Retry the command after confirming TFC status page shows no incident; transient 5xx often resolve on retry."],"exampleFix":"// before: token expired\n$ terraform plan\nError: Error retrieving state: resource not found / unauthorized\n\n// after: refresh credentials and confirm workspace\n$ terraform login app.terraform.io\n$ terraform workspace show   # confirm correct workspace selected\n$ terraform plan","handlingStrategy":"retry","validationCode":"// Validate reachability and credentials before issuing state operations.\nctx := context.Background()\nif _, err := b.client.Organizations.Read(ctx, r.organization); err != nil {\n    return fmt.Errorf(\"preflight: cannot reach TFC org %q: %w\", r.organization, err)\n}","typeGuard":null,"tryCatchPattern":"// Wrap ReadCurrent in a bounded retry for transient failures; surface fatal ones.\nvar sv *tfe.StateVersion\nerr := RetryBackoff(ctx, func() error {\n    var e error\n    sv, e = b.client.StateVersions.ReadCurrent(ctx, r.workspace.ID)\n    if e == tfe.ErrResourceNotFound { return nil }\n    return e\n})\nif err != nil { return nil, fmt.Errorf(\"Error retrieving state: %v\", err) }","preventionTips":["Use `terraform login` and store tokens via TF_TOKEN_<host> so they refresh cleanly.","Grant the service account read access on every workspace it touches.","Run a preflight Organizations.Read or Workspaces.Read to fail fast on auth/connectivity issues.","Allowlist both the TFC API host and object-storage host in egress proxies."],"tags":["state","remote-backend","network","api","auth","terraform-cloud"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T21:17:07.882Z"}