{"record":{"id":"8afb4b80aec4fd56","repo":"hashicorp/terraform","slug":"error-retrieving-state-v-8afb4b","errorCode":null,"errorMessage":"error retrieving state: %v","messagePattern":"error retrieving state: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/cloud/state.go","lineNumber":417,"sourceCode":"\ts.readSerial = stateFile.Serial\n\ts.readState = s.state.DeepCopy()\n\treturn nil\n}\n\nfunc (s *State) getStatePayload() (*remote.Payload, error) {\n\tctx := context.Background()\n\n\t// Check the x-terraform-snapshot-interval header to see if it has a non-empty\n\t// value which would indicate snapshots are enabled\n\tctx = tfe.ContextWithResponseHeaderHook(ctx, s.readSnapshotIntervalHeader)\n\n\tsv, err := s.tfeClient.StateVersions.ReadCurrent(ctx, s.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, fmt.Errorf(\"error retrieving state: %v\", err)\n\t}\n\n\tstate, err := s.tfeClient.StateVersions.Download(ctx, sv.DownloadURL)\n\tif err != nil {\n\t\treturn nil, 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":399,"sourceCodeEnd":435,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/cloud/state.go#L399-L435","documentation":"Thrown in getStatePayload when s.tfeClient.StateVersions.ReadCurrent fails for any reason other than tfe.ErrResourceNotFound (which is treated as an empty/new workspace and returns nil). This is the API call that fetches the current state version metadata for the workspace before downloading the actual state bytes. The %v (not %w) embeds the raw TFE client error string.","triggerScenarios":"Expired or invalid API token causing 401/403; network failure reaching the TFE endpoint; TFE 5xx server error; workspace deleted between the backend config read and the state read; user lacks read permission on the workspace; rate limiting (429) exhausted retries.","commonSituations":"Rotated API token not yet propagated; intermittent connectivity from CI runners to app.terraform.io; workspace permission changed by an admin removing the CI service account; TFE instance restarting or under maintenance.","solutions":["Verify the API token is valid and the authenticated identity has read access to the workspace","Check network connectivity and retry if the error is a transient HTTP failure","Confirm the workspace still exists in the specified organization","Inspect the wrapped error text for HTTP status codes (401/403 = auth, 5xx = server, 429 = rate limit)"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Before RefreshState, verify connectivity and auth:\nctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)\ndefer cancel()\nif _, err := tfeClient.Organizations.Read(ctx, organization); err != nil {\n    return fmt.Errorf(\"cannot reach TFE org %s, state refresh will fail: %w\", organization, err)\n}","typeGuard":null,"tryCatchPattern":"// Retry RefreshState for transient retrieval failures:\nbackoff := time.Second\nfor attempt := 0; attempt < 5; attempt++ {\n    err := stateMgr.RefreshState()\n    if err == nil {\n        break\n    }\n    if isRetryableHTTPError(err) {\n        time.Sleep(backoff)\n        backoff *= 2\n        continue\n    }\n    return err // auth/permission errors are not retryable\n}","preventionTips":["Validate the API token and workspace read permissions before running terraform plan/apply","Use retry-aware HTTP clients or wrappers for the TFE client in automation","Monitor TFE platform status during large plan operations that read state"],"tags":["network","state-refresh","tfe","authentication","terraform"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}