terraform force-unlock Command Reference

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 backend lock (for example 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 record only; it does not change state.

Common flags and usage

LOCK_ID: required, the lock to release (printed in the lock error)
-force: skip the confirmation prompt (CI)
Confirm no real run is in flight before forcing; check CI status, not lock age

Example

shell

# Copy the Lock ID from the "Error acquiring the state lock" message
terraform force-unlock -force 1a2b3c4d-5e6f-7890-abcd-ef1234567890

In CI

Only force-unlock after confirming no other job is genuinely running, since unlocking a live apply lets two runs write state simultaneously and corrupts it. Pass the exact Lock ID from the original error; when in doubt, wait the lock out.

Key takeaways

force-unlock removes only the lock record; it never edits state.
Use the exact Lock ID from the original lock error message.
Never unlock while a real apply is in flight; it can corrupt state.