Terraform State Refresh: Reconcile Drift Without Applying (2026)

Terraform’s refresh command can feel like magic, letting you update your state file to match the real world without touching your infrastructure.

Let’s see it in action. Imagine you’ve manually changed a security group rule in AWS, maybe to allow SSH from a new IP address. Terraform, unaware of this change, still thinks the old rule is in place.

# First, let's see what Terraform *thinks* our state is
terraform plan

# Now, let's pretend we manually changed something in AWS
# (e.g., added a new ingress rule to a security group managed by Terraform)

# To reconcile this, we run refresh
terraform refresh

# After refresh, 'terraform plan' will show the drift
terraform plan

After running terraform refresh, your next terraform plan will show the difference between what Terraform thought existed and what actually exists in your cloud provider. This is crucial because without refresh, your terraform apply might try to revert your manual changes, or worse, fail to detect actual drift and proceed with an incorrect plan.

The problem refresh solves is "state drift." Over time, the actual state of your infrastructure can diverge from the state recorded in your Terraform state file. This happens for many reasons: manual changes made directly in the cloud console, other automation tools, or even resource recreation by the cloud provider itself. If your state file is out of sync, terraform plan won’t accurately reflect the current reality, and terraform apply could lead to unexpected or destructive actions.

Internally, terraform refresh works by querying your cloud provider for the current status of every resource managed by your Terraform configuration. It then compares this real-world data against the information stored in your state file. If discrepancies are found (e.g., a resource has been modified, added, or deleted outside of Terraform), it updates the state file to match the current, actual state. It doesn’t modify your infrastructure; it only modifies your terraform.tfstate file.

Here’s a breakdown of common scenarios and how refresh helps:

• Manual Changes: You or another operator logged into the AWS console and updated an EC2 instance’s tags or modified a load balancer’s listener. terraform refresh will detect these tag changes or listener modifications and update the state file accordingly. A subsequent terraform plan will then show these as "no changes" if they were only cosmetic, or it might show a plan to revert the change if Terraform’s configuration differs and the drift is significant.

  • Diagnosis: Run terraform plan before and after terraform refresh. The difference in the plan output indicates drift.
  • Fix: Run terraform refresh. This command polls the cloud provider and updates the state file.
  • Why it works: It fetches the live state from the provider, overwriting the stale state in your *.tfstate file with the current reality.

• Resource Deletion: A critical server was accidentally terminated via the cloud provider’s interface. Terraform, unaware, still believes the resource exists.

  • Diagnosis: terraform plan will show the resource as managed, but terraform refresh will reveal it’s gone.
  • Fix: terraform refresh. Terraform will mark the resource as "destroyed" in the state file.
  • Why it works: It queries the provider, sees the resource is missing, and updates the state to reflect its non-existence.

• Provider-Managed Changes: Cloud providers sometimes update or replace underlying infrastructure. For example, an AWS RDS instance might be replaced due to maintenance.

  • Diagnosis: terraform plan might show a plan to replace the resource, or it might report no issues if the resource ID hasn’t changed but attributes have. terraform refresh clarifies.
  • Fix: terraform refresh. It will update attributes in the state file to match the new underlying details.
  • Why it works: It reads the latest configuration details from the provider, ensuring the state file accurately reflects the resource’s current attributes.

• External Automation: Another tool (e.g., Ansible, Chef, or a different Terraform workspace) modified a resource that Terraform is also managing.

  • Diagnosis: terraform plan will show a difference.
  • Fix: terraform refresh.
  • Why it works: Similar to manual changes, it synchronizes Terraform’s view with the external modifications.

• Terraform Version/Provider Plugin Updates: Sometimes, upgrading Terraform or its provider plugins can change how resources are interpreted or how their attributes are read.

  • Diagnosis: After an upgrade, terraform plan might show unexpected changes.
  • Fix: terraform refresh.
  • Why it works: It forces a re-read of all resource attributes using the new provider logic, ensuring the state file is compatible with the updated tools.

• Incomplete or Failed Applies: If a terraform apply was interrupted or failed mid-way, the state file might be in an inconsistent state relative to the actual infrastructure.

  • Diagnosis: terraform plan will show a state that doesn’t match reality.
  • Fix: terraform refresh.
  • Why it works: It provides a clean slate by re-evaluating the entire infrastructure against the provider’s current state.

It’s important to note that terraform refresh is often implicitly run by terraform plan and terraform apply by default. However, explicitly running terraform refresh is useful when you want to update your state file without immediately seeing a plan or applying changes, or when you suspect your state is significantly out of sync and want to audit the drift first.

A common, subtle pitfall is when terraform refresh updates a resource’s attributes that are not explicitly managed by your configuration. For example, if your configuration manages an EC2 instance but doesn’t specify a user_data attribute, and you’ve updated user_data manually, terraform refresh will pull that new user_data into the state. If you then run terraform apply without refresh (or if refresh wasn’t run implicitly), Terraform might try to revert that user_data change because it’s not declared in your .tf files. This is why refresh is often paired with plan to understand what would happen if you were to apply.

The next thing you’ll likely encounter after mastering state reconciliation is understanding how to manage multiple, independent Terraform state files for different environments or components.