Handling Terraform State Locking
Fast recall
Quick revision
Core answer
Whether you understand why concurrent Terraform operations on the same state cause corruption and how locking prevents it.
Using a remote backend like S3 without configuring DynamoDB for locking, which stores state remotely but does not prevent concurrent modifications.
Explain what happens on a stale lock (crash mid-apply), how to force-unlock safely, and mention that Terraform Cloud and GitLab CI handle locking natively without needing DynamoDB.
Interview-ready guide
Interview answer
Terraform state locking prevents two concurrent operations from corrupting the state file. Without locking, two engineers running apply simultaneously would both read the same state, make different changes, and race to write back — the last write wins and the first apply's changes are lost from state.
How locking works
- When a
terraform applyorplan -refreshstarts, Terraform acquires a lock on the state backend before reading state — any other operation that tries to acquire the lock waits or fails with a lock ID message - S3 backends use DynamoDB for locking:
dynamodb_table = "terraform-locks"in the backend configuration; Terraform writes a record with the lock ID to DynamoDB before reading state and deletes it after releasing - Terraform Cloud and HCP Terraform have locking built into the state API — no DynamoDB setup required; the lock is managed by the backend service
Handling stuck locks
- A
terraform applythat is killed (Ctrl+C, runner timeout, network failure) may leave a lock in place — Terraform prints the lock ID in the error message when subsequent operations are blocked terraform force-unlockremoves the lock manually — only do this after confirming that the process holding the lock is genuinely dead; force-unlocking a live process leads to the concurrent modification problem you were trying to prevent- In CI pipelines, set a pipeline timeout shorter than the lock timeout — an apply that times out in the pipeline runner should either complete cleanly or leave a lock that the next run detects, not silently abandon a half-applied change
Locking in team workflows
- The Atlantis pattern (GitHub PR comment triggers plan/apply) serializes applies through the Atlantis server — only one apply runs at a time per workspace, and the lock is held for the minimum time; this is better than multiple engineers running
terraform applyfrom their local machines simultaneously - Always configure locking before adding the first team member — retrofitting locking after a state corruption incident is a stressful exercise in reconciling diverged infrastructure
Handling Terraform State Locking
Direct Answer
State locking prevents concurrent Terraform operations from corrupting the state file. S3 backend uses DynamoDB for locking; Terraform Cloud locks natively. If a lock is stale after a crash, use terraform force-unlock with the lock ID.
Code Example
# Backend configuration with locking (AWS S3 + DynamoDB)
terraform {
backend "s3" {
bucket = "my-terraform-state"
key = "prod/terraform.tfstate"
region = "us-east-1"
encrypt = true
dynamodb_table = "terraform-locks" # REQUIRED for locking
}
}
# The DynamoDB table only needs one attribute: LockID (String, hash key)
# Create it once:
# aws dynamodb create-table \
# --table-name terraform-locks \
# --attribute-definitions AttributeName=LockID,AttributeType=S \
# --key-schema AttributeName=LockID,KeyType=HASH \
# --billing-mode PAY_PER_REQUEST
# If a lock is stale after a crash:
# terraform plan will output:
# Error: Error locking state: Error acquiring the state lock: ... ID: abc-123
#
# Force unlock ONLY after confirming no apply is running:
# terraform force-unlock abc-123
Common Mistakes & Pitfalls
Using a remote backend like S3 without configuring DynamoDB for locking, which stores state remotely but does not prevent concurrent modifications.
Check your understanding
Answer these without looking back at the article.
- How do you resolve a stale Terraform state lock safely?
- What is the difference between Terraform Cloud locking and DynamoDB locking?
- How do you configure Terraform to wait for a lock instead of failing immediately?
Related interview prep categories
1Looking for a structured roadmap?
Every module on this page is also part of the full Java backend interview track.