terraform force-unlock: Usage & Common CI Errors

Clear a stuck state lock left behind by a crashed run - carefully.

terraform force-unlock removes a state lock that was not released, usually because a plan or apply crashed or a CI job was killed mid-run.

What it does

When a run starts, Terraform acquires a lock on the backend (e.g. a DynamoDB item for S3 backends) so two runs cannot write state at once. If the process dies, the lock can persist and block all future runs. force-unlock <LOCK_ID> deletes that lock. It does not change state - only the lock record.

Common usage

Terminal

# The lock error prints the Lock ID - pass it to force-unlock
terraform force-unlock 1a2b3c4d-5e6f-7890-abcd-ef1234567890

# Skip the confirmation prompt (CI)
terraform force-unlock -force 1a2b3c4d-5e6f-7890-abcd-ef1234567890

Common error in CI: unlock fails or unlocks a live run

force-unlock can fail with "Lock Info ... does not match" if you pass the wrong ID, or - far worse - succeed and let two applies write state simultaneously, corrupting it. Fix: copy the exact Lock ID from the original "Error acquiring the state lock" message, and only force-unlock after confirming no other job is genuinely running (check CI run status, not just the lock age). When in doubt, wait the lock out rather than forcing it.

Key options

Option	Purpose
<LOCK_ID>	Required: the lock to release
-force	Skip the confirmation prompt

Related guides

Terraform "Error acquiring the state lock" - Fix Lock ContentionFix Terraform "Error acquiring the state lock" in CI - a concurrent run holds the lock, or a killed run left… Terraform State Drift - "Objects have changed outside of Terraform"Understand Terraform drift in CI - "Objects have changed outside of Terraform" and unexpected plan diffs from… Terraform "Error loading state: AccessDenied" in CIFix Terraform "Error loading state: AccessDenied" in CI - the CI role can configure the backend but lacks s3:… terraform state rm: Usage & Common CI ErrorsWhat terraform state rm does, how to stop tracking a resource without destroying it, and the locking errors y… Terraform "Error acquiring the state lock" - Fix Lock ContentionFix Terraform "Error acquiring the state lock" in CI - a concurrent run holds the lock, or a killed run left… Terraform "Local state cannot be unlocked by another process" / force-unlock fails in CIFix Terraform force-unlock failures in CI - a wrong lock ID, lock-table permissions, or a backend that no lon…