terraform refresh / -refresh-only: Usage & CI Errors

Reconcile state with the real world - the modern, safe way.

terraform refresh updates state to match real infrastructure. The standalone command is deprecated; the supported path is terraform apply -refresh-only, which lets you review drift before accepting it.

What it does

A refresh reads each managed resource from its provider and updates the recorded attributes in state - without changing any configuration. It surfaces drift (changes made outside Terraform). The legacy terraform refresh applies those updates silently; terraform apply -refresh-only shows them and asks before writing.

Common usage

Terminal

# Preferred: review drift, then accept the state update
terraform apply -refresh-only

# Non-interactive refresh in CI
terraform apply -refresh-only -auto-approve

# Detect drift as a gate without changing state
terraform plan -refresh-only -detailed-exitcode

Common error in CI: deprecation warning / unexpected drift

Pipelines using the old command get "The refresh command is deprecated" and may overwrite state with surprising drift. Fix: replace terraform refresh with terraform apply -refresh-only -auto-approve, or gate on terraform plan -refresh-only -detailed-exitcode (exit 2 = drift) and alert instead of auto-accepting. Avoid blanket auto-refresh in apply by setting -refresh=false when you have already refreshed in a prior step.

Key options

Option	Purpose
-refresh-only	Refresh mode for plan/apply
-auto-approve	Accept the state update without prompt
-detailed-exitcode	Exit 2 when drift is detected (plan)

Related guides

Terraform "Error acquiring the state lock" - Fix Lock ContentionFix Terraform "Error acquiring the state lock" in CI - a concurrent run holds the lock, or a killed run left… Terraform State Drift - "Objects have changed outside of Terraform"Understand Terraform drift in CI - "Objects have changed outside of Terraform" and unexpected plan diffs from… Terraform "Error loading state: AccessDenied" in CIFix Terraform "Error loading state: AccessDenied" in CI - the CI role can configure the backend but lacks s3:… terraform plan: Usage, Options & Common CI ErrorsWhat terraform plan does, how to save a plan file for apply in CI, detailed-exitcode for drift gates, and the… terraform apply: Usage, Options & Common CI ErrorsWhat terraform apply does, how to apply a saved plan non-interactively in CI, auto-approve, and the most comm… Terraform State Drift - "Objects have changed outside of Terraform"Understand Terraform drift in CI - "Objects have changed outside of Terraform" and unexpected plan diffs from…