{"record":{"id":"63c49a4ad4bc6d13","repo":"hashicorp/terraform","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 \"terraform apply -refresh-only\" instead.","messagePattern":"\n\nThe \"refresh\" operation is not supported when using the \"remote\" backend\\. Use \"terraform apply -refresh-only\" instead\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/backend/remote/backend.go","lineNumber":799,"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, *backendrun.Operation, *tfe.Workspace) (*tfe.Run, error)\n\tswitch op.Type {\n\tcase backendrun.OperationTypePlan:\n\t\tf = b.opPlan\n\tcase backendrun.OperationTypeApply:\n\t\tf = b.opApply\n\tcase backendrun.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 \\\"terraform 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 runninCtx is only used to block until the operation returns.\n\trunningCtx, done := context.WithCancel(context.Background())\n\trunningOp := &backendrun.RunningOperation{\n\t\tContext:   runningCtx,\n\t\tPlanEmpty: true,\n\t}\n","sourceCodeStart":781,"sourceCodeEnd":817,"githubUrl":"https://github.com/hashicorp/terraform/blob/c9def3e214014c1188faabfc4a5bde5095139765/internal/backend/remote/backend.go#L781-L817","documentation":"Operation() explicitly rejects backendrun.OperationTypeRefresh: the legacy standalone `terraform refresh` command is not supported by the remote backend. The error directs the user to the supported `terraform apply -refresh-only` workflow instead.","triggerScenarios":"Running `terraform refresh` (or any code path that sets op.Type = OperationTypeRefresh) against a workspace configured with the remote backend in remote-execution mode. The check happens after fetchWorkspace, before the plan/apply switch.","commonSituations":"A user runs `terraform refresh` out of habit or from an old script/CI job after migrating to the remote backend; an automation tool invokes the refresh subcommand.","solutions":["Replace `terraform refresh` with `terraform apply -refresh-only`, which is the remote-backend-supported equivalent.","Update CI pipelines, scripts, and Makefiles that still call `terraform refresh`."],"exampleFix":"// before\n$ terraform refresh\n\n// after\n$ terraform apply -refresh-only","handlingStrategy":"validation","validationCode":"// Reject the unsupported refresh op before dispatching to the backend.\nfunc assertNotRefresh(opType backendrun.OperationType) error {\n    if opType == backendrun.OperationTypeRefresh {\n        return errors.New(\"refresh unsupported; use apply -refresh-only\")\n    }\n    return nil\n}","typeGuard":"func isSupportedOp(t backendrun.OperationType) bool {\n    return t == backendrun.OperationTypePlan || t == backendrun.OperationTypeApply\n}","tryCatchPattern":null,"preventionTips":["Replace every `terraform refresh` invocation in scripts and CI with `terraform apply -refresh-only`.","Lint CI pipelines for the deprecated `refresh` subcommand.","Document the supported operation set for teams adopting the remote backend."],"tags":["operation","refresh","deprecated","configuration"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T21:17:07.882Z"}