Prompt
terraform state locking
Latest observation
Nov 12, 2026
OpenAI APIWeb search: off
Terraform state locking is a mechanism that prevents multiple people or automation jobs from modifying the same Terraform state at the same time.
Why it matters
Terraform state records the current real-world infrastructure. If two runs update it concurrently, you can get:
- corrupted state
- duplicate resources
- inconsistent plans/applies
- lost changes
How it works
When Terraform starts an operation that may write state, it tries to acquire a lock on the state file.
While locked:
- other
terraform plan/terraform applyoperations that need the lock will wait or fail - only one process can safely update the state
After the operation finishes, Terraform releases the lock.
Where locking is supported
Locking depends on the backend you use.
Backends that support locking
Common examples:
- S3 backend with DynamoDB lock table
- AzureRM backend
- GCS backend
- Terraform Cloud / Terraform Enterprise
- many remote backends
Local backend
- The default local state backend does not provide distributed locking
- It’s only safe if one person/process is using it
Example: S3 backend locking
In AWS, you often configure:
- S3 bucket for state storage
- DynamoDB table for lock management
Example:
terraform {
backend "s3" {
bucket = "my-terraform-state"
key = "prod/terraform.tfstate"
region = "us-east-1"
dynamodb_table = "terraform-locks"
encrypt = true
}
}
Common commands
terraform plan— usually reads state, but may still lock depending on backend and operationterraform apply— acquires lock before changing stateterraform force-unlock <LOCK_ID>— manually releases a stale lock if a run crashed
If a lock is stuck
Terraform may show an error like:
- “Error acquiring the state lock”
- includes a lock ID and info about who holds it
Typical fixes:
- Check whether another Terraform run is still active
- Wait for it to finish
- If it crashed and left a stale lock, use:
terraform force-unlock <LOCK_ID>
Be careful: only force-unlock if you’re sure no valid operation is still running.
Best practices
- Always use a backend with locking in team/shared environments
- Don’t run multiple applies against the same state at once
- Use CI/CD serialization or pipeline concurrency controls
- Protect state storage with proper permissions and encryption
If you want, I can also show:
- how locking works in S3 + DynamoDB
- how to configure a backend
- how to debug a stuck lock error