How to Handle State File Conflict in Terraform: Simple Fixes

Terraform state file conflicts happen when multiple users or processes try to change the state at the same time. To fix this, use terraform state pull to get the latest state, resolve conflicts manually if needed, and then use terraform state push or run terraform apply again. Using remote state locking helps prevent these conflicts.

Why This Happens

Terraform keeps track of your infrastructure in a state file. When two or more people or processes try to update this file at the same time, Terraform cannot merge the changes automatically. This causes a conflict error because the state file is locked or out of sync.

bash

terraform apply

# User A and User B both run terraform apply at the same time
# Both try to update the state file stored locally or remotely

# User B's apply fails with an error:

Output

Error: Error locking state: Error acquiring the state lock: ConditionalCheckFailedException: The conditional request failed

Terraform state file is locked by another process.

The Fix

First, pull the latest state file to see the current state using terraform state pull. Then, if you have local changes, merge them carefully. Finally, push the updated state back with terraform state push or run terraform apply again to update the infrastructure safely.

Using remote state with locking (like S3 with DynamoDB for AWS) prevents simultaneous edits.

bash

terraform state pull > latest.tfstate
# Review and merge changes if needed
terraform state push latest.tfstate

# Or simply run
terraform apply

Output

Apply complete! Resources: 0 added, 0 changed, 0 destroyed.

Prevention

To avoid state file conflicts:

• Use remote state storage with locking support (e.g., AWS S3 + DynamoDB, Terraform Cloud).
• Never edit the state file manually unless necessary.
• Communicate with your team to avoid running Terraform commands simultaneously.
• Use terraform plan before applying to check for conflicts.

Related Errors

Other common errors related to state conflicts include:

• State Lock Timeout: Happens when a lock is held too long; wait or manually unlock.
• State File Corruption: Caused by manual edits; restore from backup.
• Backend Configuration Mismatch: Occurs if backend settings differ between runs; ensure consistent backend config.

Key Takeaways

Always use remote state with locking to prevent conflicts.

Pull and review the latest state before pushing changes.

Avoid running Terraform commands simultaneously on the same state.

Never manually edit the state file unless absolutely necessary.

Communicate with your team to coordinate Terraform runs.