{"record":{"id":"51898fdbaa22d6d0","repo":"opentofu/opentofu","slug":"the-refresh-operation-is-not-supported-when-us","errorCode":null,"errorMessage":"\n\nThe \"refresh\" operation is not supported when using the \"remote\" backend. Use \"tofu apply -refresh-only\" instead.","messagePattern":"\n\nThe \"refresh\" operation is not supported when using the \"remote\" backend\\. Use \"tofu apply -refresh-only\" instead\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/backend/remote/backend.go","lineNumber":707,"sourceCode":"\t\t// Record that we're forced to run operations locally to allow the\n\t\t// command package UI to operate correctly\n\t\tb.forceLocal = true\n\t\tlog.Printf(\"[DEBUG] Remote backend is delegating %s to the local backend\", op.Type)\n\t\treturn b.local.Operation(ctx, op)\n\t}\n\n\t// Set the remote workspace name.\n\top.Workspace = w.Name\n\n\t// Determine the function to call for our operation\n\tvar f func(context.Context, context.Context, context.Context, *backend.Operation, *tfe.Workspace) (*tfe.Run, error)\n\tswitch op.Type {\n\tcase backend.OperationTypePlan:\n\t\tf = b.opPlan\n\tcase backend.OperationTypeApply:\n\t\tf = b.opApply\n\tcase backend.OperationTypeRefresh:\n\t\treturn nil, fmt.Errorf(\n\t\t\t\"\\n\\nThe \\\"refresh\\\" operation is not supported when using the \\\"remote\\\" backend. \" +\n\t\t\t\t\"Use \\\"tofu apply -refresh-only\\\" instead.\")\n\tdefault:\n\t\treturn nil, fmt.Errorf(\n\t\t\t\"\\n\\nThe \\\"remote\\\" backend does not support the %q operation.\", op.Type)\n\t}\n\n\t// Lock\n\tb.opLock.Lock()\n\n\t// Build our running operation\n\t// the runningCtx is only used to block until the operation returns.\n\trunningCtx, done := context.WithCancel(context.Background())\n\trunningOp := &backend.RunningOperation{\n\t\tContext:   runningCtx,\n\t\tPlanEmpty: true,\n\t}\n","sourceCodeStart":689,"sourceCodeEnd":725,"githubUrl":"https://github.com/opentofu/opentofu/blob/3561785c48c1ce615e7c50261bd351f26053efa2/internal/backend/remote/backend.go#L689-L725","documentation":"Returned by Remote.Operation (backend.go:707) when op.Type is backend.OperationTypeRefresh: the remote backend deliberately does not implement the standalone refresh operation because runs execute server-side in TFC/TFE. The message itself directs users to `tofu apply -refresh-only` instead.","triggerScenarios":"A caller invokes the Operation entry point with op.Type == OperationTypeRefresh — in practice, running `tofu refresh` (or terraform refresh) against a configuration whose backend is \"remote\" rather than \"s3\"/\"local\".","commonSituations":"Teams migrating from local/S3 backends to TFC keep refresh in scripts or CI pipelines; muscle-memory `tofu refresh` against a remote workspace; wrappers invoking refresh programmatically.","solutions":["Replace `tofu refresh` with `tofu apply -refresh-only` in scripts/CI for remote-backend configurations","If you only want to update state without applying, use `tofu apply -refresh-only` and do not confirm any changes (or use -auto-approve with no changes pending)","Switch to a backend that supports refresh (e.g. s3) if a standalone refresh is a hard requirement","Audit pipelines for the refresh command when onboarding workspaces to the remote backend"],"exampleFix":"# before\ntofu refresh\n\n# after (remote backend)\ntofu apply -refresh-only","handlingStrategy":"fallback","validationCode":"// guard your wrapper before invoking the backend\nfunc opSupportedForRemote(t backend.OperationType) bool {\n  return t == backend.OperationTypePlan || t == backend.OperationTypeApply\n}","typeGuard":"func isRefreshUnsupportedErr(err error) bool {\n  return err != nil && strings.Contains(err.Error(), `\"refresh\" operation is not supported`)","tryCatchPattern":"if _, err := b.Operation(ctx, op); err != nil {\n  if isRefreshUnsupportedErr(err) {\n    // fall back: run apply with refresh-only semantics instead\n  } else {\n    return err\n  }\n}","preventionTips":["Replace tofu refresh with tofu apply -refresh-only wherever the remote backend is used","Add a lint rule in CI rejecting refresh against remote-backed configs","Document backend capability differences during TFC migration"],"tags":["remote-backend","cli","operation","refresh"],"backgroundTag":null,"analyzedSha":"3561785c48c1ce615e7c50261bd351f26053efa2","analyzedAt":"2026-08-15T23:27:16.226Z","schemaVersion":2},"datasetVersion":"2026-08-16T03:17:38.424Z"}