Q: How does Terraform state locking work internally?

Without state locking, two engineers or automated CI runs executing terraform apply concurrently read the same baseline state, compute different resource deltas, and write conflicting state files back to S3. The second write obliterates the first write, creating orphaned infrastructure and corrupted state.

• Race Condition: Two processes mutating state simultaneously causes unrecoverable state divergence.
• Solution: A distributed locking mechanism ensuring only one mutating operation executes against a state file at any given time.

In an AWS enterprise backend, Terraform pairs Amazon S3 (for highly durable object storage) with an Amazon DynamoDB table (for distributed mutex locking). The DynamoDB table must be configured with a String primary partition key named exactly LockID.

terraform {
  backend "s3" {
    bucket         = "my-corp-tf-state-prod"
    key            = "networking/vpc.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-state-locks"
    encrypt        = true
  }
}

• S3 Responsibilities: Stores the encrypted state JSON file, version history, and object ACLs.
• DynamoDB Responsibilities: Manages ephemeral mutex lock items via atomic conditional write operations.

When you execute terraform plan or apply, Terraform computes the unique state path (e.g. my-corp-tf-state-prod/networking/vpc.tfstate-md5) and attempts an atomic DynamoDB PutItem operation.

# Conceptual DynamoDB conditional write payload executed by Terraform:
PutItem({
  TableName: "terraform-state-locks",
  Item: {
    "LockID": {"S": "my-corp-tf-state-prod/networking/vpc.tfstate-md5"},
    "Info": {"S": "{\"ID\":\"c84e1b-9...\",\"Operation\":\"Plan\",\"Who\":\"alice@laptop\",\"Created\":\"2026-10-29T12:00:00Z\"}"}
  },
  ConditionExpression: "attribute_not_exists(LockID)"
})

• Atomic Guarantee: The ConditionExpression: attribute_not_exists(LockID) ensures that if another process has already written the LockID, the write fails immediately.
• Lock Collision: If locked, Terraform halts with an error displaying who acquired the lock, their hostname, operation type, and timestamp.

Once the operation finishes (whether it succeeds, fails with a validation error, or is gracefully cancelled via SIGINT/Ctrl+C), Terraform issues a DynamoDB DeleteItem operation to remove the LockID entry.

• Clean Exit: Deleting the DynamoDB record releases the mutex, allowing the next queued process to acquire the lock.
• Read-Only Operations: Operations like terraform state list or terraform output do not acquire write locks, or can bypass locking safely via -lock=false.

Technical comparison of state locking mechanisms across popular Terraform backends:

If a CI/CD runner crashes, an EC2 spot instance terminates unexpectedly, or an engineer forcibly kills a terminal with kill -9, the DeleteItem call never runs. The LockID remains stuck in DynamoDB, blocking all future runs.

# Error acquiring the state lock:
# Lock Info:
#   ID:        e05179a0-1011-4dc5-b772-00a9dc404121
#   Path:      my-corp-tf-state-prod/networking/vpc.tfstate
#   Operation: OperationTypeApply
#   Who:       runner@github-actions

# Step 1: Verify NO process is currently running on the runner
# Step 2: Forcibly unlock using the exact Lock ID
terraform force-unlock e05179a0-1011-4dc5-b772-00a9dc404121

• Verification Pre-Flight: ALWAYS verify that no running pipeline is actually in the middle of writing resources before unlocking.
• Manual DynamoDB Removal: As a fallback, deleting the item directly from the DynamoDB console or AWS CLI achieves the same result.