{"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/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/backend/remote/backend.go#L781-L817","documentation":"Hard rejection of the legacy 'terraform refresh' command when the remote backend is configured. The remote backend's Operation switch handles OperationTypeRefresh by returning this error pointing users to the supported 'terraform apply -refresh-only' equivalent. The standalone refresh command is deprecated upstream.","triggerScenarios":"op.Type == backendrun.OperationTypeRefresh dispatched through Remote.Operation. Caused by running 'terraform refresh' (or any caller invoking the refresh operation) while a 'remote' (or migrated) backend is active.","commonSituations":"User runs 'terraform refresh' from habit or an old CI script; a wrapper tool invokes the refresh operation; scripts not yet updated after migrating from local state to remote backend.","solutions":["Replace 'terraform refresh' with 'terraform apply -refresh-only' in your workflow.","If you need a pure state refresh without apply, use the 'cloud' backend or switch to a local backend temporarily.","Update CI pipelines and documentation that still invoke 'terraform refresh'."],"exampleFix":"# before\nterraform refresh\n# after\nterraform apply -refresh-only","handlingStrategy":"validation","validationCode":"// Reject 'refresh' before dispatch if a remote backend is configured.\nfunc assertOpSupported(op string, backend string) error {\n    if backend == \"remote\" && op == \"refresh\" {\n        return errors.New(`use 'terraform apply -refresh-only' with the remote backend`)\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Audit CI scripts and docs for 'terraform refresh' and migrate them to 'apply -refresh-only'.","Add a pre-flight lint that errors on 'refresh' when the remote/cloud backend is active."],"tags":["backend","remote-backend","operation","refresh","deprecated","go"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}