hashicorp/terraform · error

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

Error message

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

What it means

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.

Solutions

1. Replace 'terraform refresh' with 'terraform apply -refresh-only' in your workflow.
2. If you need a pure state refresh without apply, use the 'cloud' backend or switch to a local backend temporarily.
3. Update CI pipelines and documentation that still invoke 'terraform refresh'.

Example fix

# before
terraform refresh
# after
terraform apply -refresh-only

// Reject 'refresh' before dispatch if a remote backend is configured.
func assertOpSupported(op string, backend string) error {
    if backend == "remote" && op == "refresh" {
        return errors.New(`use 'terraform apply -refresh-only' with the remote backend`)
    }
    return nil
}

When it happens

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

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

Related errors

• The "remote" backend does not support the
• Error asking
• Error creating workspace
• error finding remote workspace
• error loading state

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

Appendix: 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 d32a084675)