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
# Copy the Lock ID from the "Error acquiring the state lock" message
terraform force-unlock -force 1a2b3c4d-5e6f-7890-abcd-ef1234567890In 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.
Using this in CI
Cloud CLIs behave differently on a runner than on your laptop. They assume no interactive terminal, no cached credentials, and no browser for device-code flows, so the same command that works locally can hang or fail on a runner.
- Authenticate with a short-lived OIDC token rather than a long-lived static key. GitHub Actions can exchange
id-token: writefor cloud credentials with no stored secret. - Always pass the non-interactive flag. Most cloud CLIs will otherwise prompt and hang until the job times out.
- Pin the CLI version. Cloud CLIs change output formats between minor releases, and any script parsing that output will break silently.
- Set the output format explicitly (
--output json) rather than relying on the default, which can differ by version and configuration profile.
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.