terraform state lock

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

Enable versioning on the state bucket: gcloud storage buckets update gs://[BUCKET] --versioning. Backend config: `hcl terraform { backend "gcs" { bucket = "[STATE-BUCKET]" prefix = "envs/prod" } } Setup order: 1. Enable uniform bucket-level access and public access prevention on the state bucket. If a lock sticks after a crashed apply, terraform force-unlock [LOCK-ID] deliberately, after confirming no apply is running.

When to use

You are seeing this: Goal: shared, safe terraform state for a team. Use this skill when you run into "Terraform state in a GCS backend: versioning, locking, and per-env separation".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Goal: shared, safe terraform state for a team.

Backend config:

terraform {
  backend "gcs" {
    bucket = "[STATE-BUCKET]"
    prefix = "envs/prod"
  }
}

Setup order:

1. Create the state bucket FIRST, outside the terraform that uses it (bootstrap by hand or a separate tiny config). Chicken-and-egg otherwise.
2. Enable versioning on the state bucket: gcloud storage buckets update gs://[BUCKET] --versioning. Corrupted state is recoverable from a prior version.
3. Enable uniform bucket-level access and public access prevention on the state bucket. State files contain secrets.
4. Grant the CI/human identities storage.objectAdmin on the bucket (terraform needs read/write, and locking).

Locking: the GCS backend handles state locking natively. Do not disable it. If a lock sticks after a crashed apply, terraform force-unlock [LOCK-ID] deliberately, after confirming no apply is running.

Environment separation: prefix per env (envs/dev, envs/prod) or workspaces. Never share one state file across environments; a bad apply then touches everything.

Traps:

• State bucket in the SAME terraform config that uses it: the backend needs the bucket before init. Bootstrap separately.
• No versioning: one bad apply corrupts state with no recovery. This is the most expensive terraform mistake on GCP.
• Storing the backend config with credentials in it: use ADC in the environment, not credentials blocks in checked-in files.
• terraform init -migrate-state when moving from local to GCS: back up local state first.

Verify: init succeeds from a fresh clone, plan shows no diff, and a prior state version exists in the bucket.

Verified 2026-09-26: the GCS backend is the documented Terraform backend for GCP; versioning-for-recovery and bootstrap-ordering are documented operational guidance. State-contains-secrets is why the access controls matter.