{"record":{"id":"9f3d7d841bd6268c","repo":"hashicorp/terraform","slug":"error-uploading-state-in-compatibility-mode-v","errorCode":null,"errorMessage":"error uploading state in compatibility mode: %v","messagePattern":"error uploading state in compatibility mode: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/backend/remote/backend_state.go","lineNumber":104,"sourceCode":"\t\tLineage:          tfe.String(stateFile.Lineage),\n\t\tSerial:           tfe.Int64(int64(stateFile.Serial)),\n\t\tMD5:              tfe.String(fmt.Sprintf(\"%x\", md5.Sum(state))),\n\t\tForce:            tfe.Bool(r.forcePush),\n\t\tState:            tfe.String(base64.StdEncoding.EncodeToString(state)),\n\t\tJSONStateOutputs: tfe.String(base64.StdEncoding.EncodeToString(jsonStateOutputs)),\n\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_, err := r.client.StateVersions.Create(ctx, r.workspace.ID, options)\n\tif err != nil {\n\t\tr.stateUploadErr = true\n\t\treturn fmt.Errorf(\"error uploading state in compatibility mode: %v\", err)\n\t}\n\treturn err\n}\n\n// Put the remote state.\nfunc (r *remoteClient) Put(state []byte) tfdiags.Diagnostics {\n\tvar diags tfdiags.Diagnostics\n\tctx := context.Background()\n\n\t// Read the raw state into a Terraform state.\n\tstateFile, err := statefile.Read(bytes.NewReader(state))\n\tif err != nil {\n\t\treturn diags.Append(fmt.Errorf(\"error reading state: %s\", err))\n\t}\n\n\tov, err := jsonstate.MarshalOutputs(stateFile.State.RootOutputValues)\n\tif err != nil {\n\t\treturn diags.Append(fmt.Errorf(\"error reading output values: %s\", err))","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/backend/remote/backend_state.go#L86-L122","documentation":"Fallback path taken only when StateVersions.Upload returns ErrStateVersionUploadNotSupported (TFE v202306-1 and older which can't accept streamed uploads). The fallback inlines the base64 state into StateVersions.Create; if that legacy Create call fails, this error is returned and r.stateUploadErr is flagged so the workspace is NOT auto-unlocked.","triggerScenarios":"uploadStateFallback's StateVersions.Create returns an error on an old TFE server: legacy upload API rejected the payload (size limit, malformed MD5/lineage), 401/403 on state write, or the server errored mid-write.","commonSituations":"Old Terraform Enterprise deployment that hasn't been upgraded past v202306-1; force-push on a serial the legacy server rejects; very large state exceeding legacy inline-upload limits; token lacks 'Write State' permission.","solutions":["Upgrade TFE to v202307-1 or later so the streamed Upload path is used (this fallback is a compatibility shim).","If upgrade isn't possible, reduce state size (split resources, prune stale data) to stay under legacy inline limits.","Verify the token has 'Write State' / admin permission on the workspace.","Inspect the wrapped error for HTTP status — 409 serial conflicts need -force on the state push."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"// Detect legacy server up front and warn\nif _, err := c.StateVersions.Upload(ctx, wsID, opts); errors.Is(err, tfe.ErrStateVersionUploadNotSupported) {\n    log.Println(\"TFE server is pre-v202307-1; falling back to inline upload\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Upgrade TFE past v202306-1 to retire this fallback.","Keep state size modest on legacy servers (inline base64 inflates payload ~33%).","Ensure 'Write State' permission for the operating token."],"tags":["terraform","remote-backend","tfe","state-upload","compatibility","legacy-tfe"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}