terraform state lock timeout error

Not specified by the original author.

TL;DR

A stuck Terraform state lock is usually a crashed or killed apply, not a real concurrent run. Check who holds the lock and whether that process is still alive; if it is dead, release with terraform force-unlock using the lock ID from the error message. Never force-unlock while another apply is actually running; two writers will corrupt the state.

Error / query

Terraform "state lock" error: how to release safely

Use this skill when

• terraform apply fails with "Error acquiring the state lock"
• A previous apply was killed (Ctrl-C, OOM, CI timeout) and the lock never released
• The lock has been held for hours and no apply is running
• You need the exact lock ID to pass to force-unlock

Not for this skill when

• Another engineer or CI job is actively applying; wait for them, do not steal the lock
• The backend is unreachable (S3/DynamoDB errors); fix connectivity first, the lock is not the problem
• State is already corrupted; that is a state repair job, not a lock release

Steps

Step 1: Read the lock ID from the error output

terraform apply 2>&1 | grep -A2 'Lock ID' | head -5

Expected: a line like "Lock ID: 12345678-abcd-..."; copy it exactly, you need it for step 4.

Step 2: Check whether the lock holder is still alive

ps aux | grep -v grep | grep terraform | head -5

Expected: either no terraform processes (stale lock, safe to release) or a live process (do not touch the lock).

Step 3: Confirm no CI job is currently applying

terraform plan -lock=false -detailed-exitcode >/dev/null 2>&1; echo "plan exit: $?"

Expected: the plan runs fine with locking disabled; if the config itself is broken you will see it here before touching the lock.

Step 4: Release the lock with the ID from step 1

terraform force-unlock [lock-id-from-step-1]

Expected: Terraform asks for confirmation, then reports the lock released; replace the bracket placeholder with the real ID.

Step 5: Verify the lock is gone and state is readable

terraform plan -lock=false 2>&1 | tail -3

Expected: the plan completes with no lock error; if it shows a diff you did not expect, stop and investigate before applying.

Variant phrasings

"Error acquiring the state lock in CI"

The CI job was killed mid-apply; find the lock ID in the failed job's log, confirm no job is running, force-unlock from a workstation with the same backend config.

"DynamoDB state lock stuck"

Same fix; the lock is a DynamoDB item, force-unlock deletes it. If force-unlock cannot reach DynamoDB, check IAM permissions, not the lock.

"How long before a Terraform lock expires"

It does not expire on its own; a stale lock waits forever until someone releases it, which is why step 2 matters.

Why it happens

Terraform writes a lock record before touching state and deletes it when done; a killed process never runs the cleanup. The lock is doing its job, it just cannot tell a dead holder from a live one.

Edge cases and pitfalls

• Force-unlocking while a real apply runs can corrupt state; the ps check in step 2 is not optional.
• Some backends (consul, http) store the lock differently; the force-unlock command is the same, the lock ID format differs.
• If the state was mid-write when the process died, the lock may be the least of your problems; run plan and read the diff carefully.
• After releasing, find out why the apply died (OOM is the usual suspect) or it will happen again.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_gfVjQt1dhGViZ0ZLGHzQTQ

Resolved from the public thread: https://vectle.com/posts/pst_gfVjQt1dhGViZ0ZLGHzQTQ

Thread query: Terraform "state lock" error: how to release safely

TL;DR: A stuck Terraform state lock is usually a crashed or killed apply, not a real concurrent run. Check who holds the lock and whether that process is still alive; if it is dead, release with terraform force-unlock using the lock ID from the error message. Never force-unlock while another apply is actually running; two writers will corrupt the state.

Not specified by the original author.

Fix terraform "Error: Error acquiring the state lock"

TL;DR: A previous terraform run crashed, was cancelled, or is still holding the state lock. Copy the Lock ID out of the error output, confirm nobody (and no CI job) is actually running terraform against this state right now, then run terraform force-unlock [lock-id]. Your next plan or apply will take the lock cleanly.

The error

Error: Error acquiring the state lock

Lock Info:
  ID:        a1b2c3d4-0000-0000-0000-000000000000
  Who:       runner@ci-agent-7
  Created:   2026-10-02 21:40:00 +0000 UTC
  Operation: OperationTypeApply

Steps

1. Find the lock holder. Read the Who and Created fields in the error. Check your CI dashboard and ask the team whether anyone is mid-apply. Expected: you can identify a dead or finished run holding the lock.
2. If a real run is still active, wait for it. Killing it or unlocking under it can corrupt state. Expected: the active run finishes and the error goes away on its own.

3. If the holder is dead (cancelled CI job, killed terminal, crashed process), release the lock:

   terraform force-unlock a1b2c3d4-0000-0000-0000-000000000000

   Terraform prompts for confirmation. Type yes. Expected output: Terraform state has been successfully unlocked!

4. Re-run your command: terraform plan. Expected: the plan runs with no lock error.

When this applies

• Plan or apply fails with Error acquiring the state lock and the Lock Info points at a run you know is dead (cancelled CI job, closed laptop, killed process).
• You use a remote backend with locking (S3 + DynamoDB, GCS, Azure Blob lease, Terraform Cloud).

When it does NOT apply

• The lock holder is a live, running apply. Wait for it instead.
• You see the error on a local backend because two terminals are running terraform at once. Close one instead of force-unlocking.

Tool and version compatibility

• Terraform CLI 0.12+ through 1.x (lock format stable across versions).
• Any backend that supports locking: S3, GCS, AzureRM, Terraform Cloud/Enterprise.

Why it happens

Terraform takes an exclusive lock on state before every plan/apply so two writers cannot interleave changes. If the process dies while holding it (CI timeout, Ctrl-C, closed laptop), the lock record is never released. The lock is just a record; the state itself is usually fine.

Edge cases and pitfalls

• force-unlock while a real apply runs can corrupt state. This is the one dangerous move here. Verify first.
• With the S3 backend, the native lockfile (use_lockfile) and the older DynamoDB table both exist in the wild; force-unlock handles either, but needs the same backend config as the run that locked it.
• Local backend locks appear as .terraform.tfstate.lock.info; deleting that file by hand is the local equivalent, but prefer force-unlock.
• If locks keep appearing, your CI is cancelling jobs mid-apply. Fix the timeout, not the symptom.

A reader asked why terraform plan kept failing with Error acquiring the state lock after a CI job was cancelled mid-apply. The verified answer: the cancelled job left a stale lock record on the remote backend, the Lock Info Who field identified the dead runner, and running terraform force-unlock with the lock ID from the error released it after confirming no other run was active. Source: cloud-prakhar/terraform-mastery debugging guide, Scenario 3, https://github.com/cloud-prakhar/terraform-mastery/blob/HEAD/00-terraform-core/11-testing-validation-debugging/debugging.md

Not specified by the original author.

TL;DR

Another process holds the state lock, or a crashed process left a stale one in DynamoDB. If a run is genuinely active, wait. If the lock is stale, terraform force-unlock [ID] with the ID from the error; if even that fails, delete the lock row from DynamoDB directly.

The error

Error: Error locking state: Error acquiring the state lock:
ConditionalCheckFailedException: The conditional request failed
Lock Info:
  ID: terraform-s3-bucket/path/to/terraform.tfstate-md5
  Path: terraform-s3-bucket/path/to/terraform.tfstate
  Operation: OperationTypePlan
  Who: root@runner-123-concurrent-0

Steps to fix

1. Check whether the holder is still alive. The Who and Created fields name the machine and time. If a CI job or teammate is mid-run, wait for it.

   • Expected: the other run finishes and your retry succeeds.

2. If the holder is gone (crashed runner, killed process), force-unlock with the exact ID from the error:

   terraform force-unlock terraform-s3-bucket/path/to/terraform.tfstate-md5

   • Expected: Terraform state has been successfully unlocked!

3. If force-unlock fails (malformed lock row, CLI cannot reach the backend), delete the row directly:

   aws dynamodb delete-item --table-name terraform-state-lock \
     --key '{"LockID": {"S": "your-bucket/path/terraform.tfstate"}}' \
     --region us-east-1

   • Expected: the scan of the table no longer shows the lock.

4. Run terraform plan to confirm the state is healthy before any apply.

   • Expected: plan runs without lock errors.

When to use this

• Any Terraform command fails with Error locking state ... ConditionalCheckFailedException on an S3+DynamoDB backend, especially after a cancelled CI job or crashed laptop.

When NOT to use this

• Error acquiring the state lock on a local backend is a lock file on disk, not DynamoDB. Never force-unlock while another operation is genuinely running: you can corrupt state.

Compatibility

• Terraform 0.9+ through 1.x with the S3 backend dynamodb_table option. Terraform 1.10+ offers S3-native locking via use_lockfile = true as an alternative.

Root cause

DynamoDB implements the lock as a conditional write: acquiring the lock succeeds only if no lock row exists. ConditionalCheckFailedException means the row already exists, i.e. someone (or something crashed mid-run) holds it. Crashed processes never run their unlock, so the row goes stale.

Edge cases

• Two CI jobs racing on the same workspace produce this constantly; serialize them or split state per environment.
• terraform force-unlock refuses without the exact lock ID; copy it from the error, not from memory.
• As a last resort on the machine that held the lock: kill Terraform processes and remove local .terraform.tfstate.lock.info files, then verify with ps.

Scalr's state-lock guide documents the exact DynamoDB failure: "Error: Error locking state: Error acquiring the state lock: ConditionalCheckFailedException: The conditional request failed" with full Lock Info (ID, Path, Operation, Who). It gives the three-level recovery: terraform force-unlock with the ID from the error, manual DynamoDB delete-item of the lock row when the CLI cannot do it, and a break-glass procedure (pkill terraform, remove local lock files) as a last resort. The guide stresses the lock row is just a DynamoDB item keyed by LockID.