State Locking

When two people — or two CI jobs — run apply against the same state at once, they can corrupt it. Each refreshes, plans, and writes back a version that does not include the other's changes; the second write overwrites the first, and state ends up reflecting neither run. State locking prevents this by taking an exclusive lock for the duration of any state-mutating operation.

With the S3 backend, modern Terraform can lock using S3 itself through a lockfile, introduced in 1.10. Older setups bolted on a DynamoDB table to hold the lock. Both work; the lockfile is one fewer resource to provision and is the current recommendation.

The Race Condition

Picture two engineers applying within the same minute. Both read serial 17. Both compute a plan against it. The first writes serial 18; the second, still holding its view of 17, writes its own serial 18 a moment later and silently erases the first's changes. No error fires — the state file is valid JSON — but it now describes a reality that never existed, and the next plan will try to "fix" the divergence by destroying or recreating real resources. Locking exists to make the second run wait instead of clobbering.

How Locking Works

Before any operation that writes state — apply, destroy, state mv, import — Terraform acquires a lock, performs the work, then releases it. A second run that finds the lock held either waits or fails fast with the lock's ID and who holds it. The lock is advisory between Terraform runs, not a filesystem lock, which is why every shared backend needs an explicit mechanism rather than assuming the operating system handles it.

S3 Native Locking

Setting use_lockfile = true on the S3 backend (Terraform 1.10+) makes S3 itself the lock. Terraform writes a small lock object alongside the state using a conditional put — the write only succeeds if the lock object does not already exist — so two simultaneous applies cannot both acquire it. There is no separate table to create, key, or pay for; the bucket you already have does the job.

terraform {
  backend "s3" {
    bucket       = "acme-tfstate-prod"
    key          = "network/terraform.tfstate"
    region       = "us-east-1"
    use_lockfile = true
  }
}

DynamoDB Locking (Legacy)

Before 1.10, the established approach was a DynamoDB table with a partition key named LockID. The backend's dynamodb_table argument points at it, and Terraform writes a conditional item to claim the lock. It still works and is everywhere in existing configs, so you will read it for years — but a wrongly keyed table (anything other than a string key called LockID) silently fails to lock, giving you the false comfort of a lock mechanism that never engages.

terraform {
  backend "s3" {
    bucket         = "acme-tfstate-prod"
    key            = "network/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "acme-tflock"
  }
}

Stuck Locks

When a process dies mid-apply — a killed CI job, a dropped laptop connection — the lock can linger because nothing released it. terraform force-unlock LOCK_ID clears it, using the ID Terraform printed when it refused to run. This is the nuclear option, not a routine fix: force-unlocking a lock that a still-running apply actually holds lets a second apply corrupt state exactly the way locking was meant to prevent. Confirm no apply is running before you reach for it.