{"record":{"id":"57b27584b111c5d9","repo":"hashicorp/terraform","slug":"error-uploading-state-v","errorCode":null,"errorMessage":"error uploading state: %v","messagePattern":"error uploading state: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/backend/remote/backend_state.go","lineNumber":156,"sourceCode":"\t}\n\n\t// If we have a run ID, make sure to add it to the options\n\t// so the state will be properly associated with the run.\n\tif r.runID != \"\" {\n\t\toptions.Run = &tfe.Run{ID: r.runID}\n\t}\n\n\t// Create the new state.\n\t// Create the new state.\n\t_, err = r.client.StateVersions.Upload(ctx, r.workspace.ID, options)\n\tif errors.Is(err, tfe.ErrStateVersionUploadNotSupported) {\n\t\t// Create the new state with content included in the request (Terraform Enterprise v202306-1 and below)\n\t\tlog.Println(\"[INFO] Detected that state version upload is not supported. Retrying using compatibility state upload.\")\n\t\treturn diags.Append(r.uploadStateFallback(ctx, stateFile, state, o))\n\t}\n\tif err != nil {\n\t\tr.stateUploadErr = true\n\t\treturn diags.Append(fmt.Errorf(\"error uploading state: %v\", err))\n\t}\n\n\treturn nil\n}\n\n// Delete the remote state.\nfunc (r *remoteClient) Delete() tfdiags.Diagnostics {\n\tvar diags tfdiags.Diagnostics\n\terr := r.client.Workspaces.Delete(context.Background(), r.organization, r.workspace.Name)\n\tif err != nil && err != tfe.ErrResourceNotFound {\n\t\treturn diags.Append(fmt.Errorf(\"error deleting workspace %s: %v\", r.workspace.Name, err))\n\t}\n\n\treturn nil\n}\n\n// EnableForcePush to allow the remote client to overwrite state\n// by implementing remote.ClientForcePusher","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/backend/remote/backend_state.go#L138-L174","documentation":"Primary state-upload path: StateVersions.Upload streams the raw state plus metadata to TFC/TFE. ErrStateVersionUploadNotSupported is handled separately (compatibility fallback); every other failure is flagged via r.stateUploadErr=true (which suppresses auto-unlock) and returned here.","triggerScenarios":"StateVersions.Upload returns an error other than ErrStateVersionUploadNotSupported: serial conflict (current state serial >= upload serial without force), workspace locked by another run, 401/403, state-too-large, 5xx, or network failure during streaming.","commonSituations":"Two concurrent applies racing on the same workspace; `terraform apply` after a state push that bumped the serial; token lacks write permission; very large state hitting the upload ceiling; TFC storage backend degraded.","solutions":["If the error is a serial/lineage conflict, re-pull state and re-plan rather than forcing.","Use -force (force-push) only if you intentionally want to overwrite history.","Ensure no other run/user is concurrently writing to the workspace.","Confirm the token has 'Write State' permission and the upload size is under the TFC limit.","On transient 5xx/network errors, re-run; stateUploadErr will require an explicit unlock."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Reject serial regressions client-side before upload\nif cur != nil && !force && uploadSerial <= cur.Serial {\n    return fmt.Errorf(\"refusing to push serial %d over current %d (use force)\", uploadSerial, cur.Serial)\n}","typeGuard":null,"tryCatchPattern":"// Retry only transient 5xx/network, not serial/lock conflicts\nif errors.Is(err, tfe.ErrStateVersionUploadNotSupported) { /* fallback */ }\nif isTransient(err) { backoff.Retry(upload, ...) } else { flagUnlockRequired(err) }","preventionTips":["Serialize concurrent applies on a workspace (TFC queue or external lock).","Re-pull state and re-plan rather than forcing on serial conflicts.","Ensure the operating token has 'Write State' permission."],"tags":["terraform","remote-backend","tfe","state-upload","lock-conflict","permissions"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}