{"record":{"id":"471321ce370d23ff","repo":"hashicorp/terraform","slug":"failed-checking-for-existing-remote-state-s","errorCode":null,"errorMessage":"failed checking for existing remote state: %s","messagePattern":"failed checking for existing remote state: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/cloud/state.go","lineNumber":186,"sourceCode":"\tlog.Printf(\"[DEBUG] cloud/state: state read serial is: %d; serial is: %d\", s.readSerial, s.serial)\n\tlog.Printf(\"[DEBUG] cloud/state: state read lineage is: %s; lineage is: %s\", s.readLineage, s.lineage)\n\n\tif s.readState != nil {\n\t\tlineageUnchanged := s.readLineage != \"\" && s.lineage == s.readLineage\n\t\tserialUnchanged := s.readSerial != 0 && s.serial == s.readSerial\n\t\tstateUnchanged := statefile.StatesMarshalEqual(s.state, s.readState)\n\t\tif stateUnchanged && lineageUnchanged && serialUnchanged {\n\t\t\t// If the state, lineage or serial haven't changed at all then we have nothing to do.\n\t\t\treturn nil\n\t\t}\n\t\ts.serial++\n\t} else {\n\t\t// We might be writing a new state altogether, but before we do that\n\t\t// we'll check to make sure there isn't already a snapshot present\n\t\t// that we ought to be updating.\n\t\terr := s.refreshState()\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"failed checking for existing remote state: %s\", err)\n\t\t}\n\t\tlog.Printf(\"[DEBUG] cloud/state: after refresh, state read serial is: %d; serial is: %d\", s.readSerial, s.serial)\n\t\tlog.Printf(\"[DEBUG] cloud/state: after refresh, state read lineage is: %s; lineage is: %s\", s.readLineage, s.lineage)\n\n\t\tif s.lineage == \"\" { // indicates that no state snapshot is present yet\n\t\t\tlineage, err := uuid.GenerateUUID()\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"failed to generate initial lineage: %v\", err)\n\t\t\t}\n\t\t\ts.lineage = lineage\n\t\t\ts.serial++\n\t\t}\n\t}\n\n\tf := statefile.New(s.state, s.lineage, s.serial)\n\n\tvar buf bytes.Buffer\n\terr := statefile.Write(f, &buf)","sourceCodeStart":168,"sourceCodeEnd":204,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/cloud/state.go#L168-L204","documentation":"Thrown by the cloud state writer when s.refreshState() fails during the 'no prior state known' branch. Before writing a brand-new state snapshot, the backend refreshes to check for an existing snapshot it should update; if that refresh read fails, the write is aborted to avoid clobbering or duplicating state.","triggerScenarios":"refreshState reads the current remote state over the TFE state API; it errors on auth failure, network/transport error, 5xx, or a corrupted/unreadable current state object. The error is wrapped (non-%w, plain %s) into this message.","commonSituations":"First apply to a workspace whose state backend has a permission issue; token lost read access to state mid-run; TFE state storage (S3/etc.) misconfigured or temporarily unavailable; network blip during the pre-write read.","solutions":["Verify the token's team has 'State Versions: Read' (and Write) on the workspace.","Re-run `terraform login` if the token may have expired.","Retry the apply — refreshState is a transient read that often clears on retry.","Inspect the underlying %s cause: storage errors point to TFE backend config, auth errors to token/permissions.","Confirm the workspace's state storage backend is healthy."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Pre-flight: confirm read access to current remote state.\nif err := s.refreshState(); err != nil {\n    return fmt.Errorf(\"preflight state read failed: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"if err := s.refreshState(); err != nil {\n    return fmt.Errorf(\"failed checking for existing remote state: %s\", err)\n}","preventionTips":["Grant 'State Versions: Read' and 'Write' to the token's team.","Keep the workspace state storage backend healthy.","Retry transient refresh failures before writing state."],"tags":["terraform","state","remote-state","auth","network","tfe"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}