hashicorp/terraform · error

The "refresh" operation is not supported when using the "r

Error message

The "refresh" operation is not supported when using the "remote" backend. Use "terraform apply -refresh-only" instead.

What it means

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.

Source

Thrown at internal/backend/remote/backend.go:799

		// Record that we're forced to run operations locally to allow the
		// command package UI to operate correctly
		b.forceLocal = true
		log.Printf("[DEBUG] Remote backend is delegating %s to the local backend", op.Type)
		return b.local.Operation(ctx, op)
	}

	// Set the remote workspace name.
	op.Workspace = w.Name

	// Determine the function to call for our operation
	var f func(context.Context, context.Context, *backendrun.Operation, *tfe.Workspace) (*tfe.Run, error)
	switch op.Type {
	case backendrun.OperationTypePlan:
		f = b.opPlan
	case backendrun.OperationTypeApply:
		f = b.opApply
	case backendrun.OperationTypeRefresh:
		return nil, fmt.Errorf(
			"\n\nThe \"refresh\" operation is not supported when using the \"remote\" backend. " +
				"Use \"terraform apply -refresh-only\" instead.")
	default:
		return nil, fmt.Errorf(
			"\n\nThe \"remote\" backend does not support the %q operation.", op.Type)
	}

	// Lock
	b.opLock.Lock()

	// Build our running operation
	// the runninCtx is only used to block until the operation returns.
	runningCtx, done := context.WithCancel(context.Background())
	runningOp := &backendrun.RunningOperation{
		Context:   runningCtx,
		PlanEmpty: true,
	}

View on GitHub (pinned to c9def3e214)

Solutions

1. Replace `terraform refresh` with `terraform apply -refresh-only`, which is the remote-backend-supported equivalent.
2. Update CI pipelines, scripts, and Makefiles that still call `terraform refresh`.

Example fix

// before
$ terraform refresh

// after
$ terraform apply -refresh-only

// Reject the unsupported refresh op before dispatching to the backend.
func assertNotRefresh(opType backendrun.OperationType) error {
    if opType == backendrun.OperationTypeRefresh {
        return errors.New("refresh unsupported; use apply -refresh-only")
    }
    return nil
}

func isSupportedOp(t backendrun.OperationType) bool {
    return t == backendrun.OperationTypePlan || t == backendrun.OperationTypeApply
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• The "remote" backend does not support the %q operation.
• default workspace not supported You can create a new workspa
• failed to append certs
• the secret name %v is invalid, {validationErrors} This is a
• root module not found. Please run terraform init

AI-assisted analysis of hashicorp/terraform@c9def3e214 (2026-08-07). Data as JSON: /api/errors/63c49a4ad4bc6d13. Report an issue: GitHub.