Terraform Lock Timeout Calculator
Calculate a safe state lock timeout from expected apply duration and flag stale lock risk.
Inputs
Typical time for `terraform apply` to complete on this configuration.
Multiplier applied to expected apply time to set the lock timeout.
How many CI/CD pipelines might attempt to acquire this lock around the same time.
Recommended Lock Timeout
16mmin
Stale Lock Risk
Moderate
Worst-Case Queue Wait
16mmin
Total Worst-Case Wait
32mmin
Step by step
Lock timeout: expected apply × safety factor
8 × 2
= 16.0 min
Worst-case queue wait (N-1 pipelines ahead)
8 × (3 - 1)
= 16.0 min
How it works
Formula: timeout = expected_apply_time × safety_factor. Setting `-lock-timeout` (or your backend's equivalent) too low causes spurious 'state locked' failures when a legitimate apply is simply still running; setting it too high means a genuinely stuck/crashed process holds the lock for a long time before anyone notices. The safety factor buys margin for applies that run longer than typical without masking real stale-lock problems indefinitely.
Formula
lock_timeout_min = expected_apply_minutes × safety_factor
- expected_apply_minutes
- Typical terraform apply duration (minutes)
- safety_factor
- Multiplier for headroom above expected duration
Frequently Asked Questions
What causes a stale Terraform lock?
A stale lock happens when a process acquires the state lock (e.g. via DynamoDB for S3 backends) but crashes, gets killed, or loses network connectivity before releasing it — the lock then blocks all future applies until manually cleared.
How do I manually clear a stuck lock?
As a last resort, `terraform force-unlock <LOCK_ID>` removes the lock — but only do this after confirming no apply is genuinely still running, since forcing an unlock during an active apply can corrupt state.
Should CI pipelines queue or fail fast on lock contention?
For infrastructure changes, queuing (retrying until the timeout) is usually safer than failing fast, since it avoids partial applies from a canceled run — but very long queues suggest you need fewer concurrent pipelines targeting the same state.
How does this interact with workspace splitting?
Splitting a monolithic configuration into workspaces/root modules with independent state files eliminates most lock contention entirely, since unrelated changes no longer compete for the same lock.
You might also need
- Terraform Workspace CalculatorCommonly used together
- Terraform Backend Storage CalculatorCommonly used together
- Terraform Apply Time CalculatorCommonly used together
- Terraform Refresh Duration CalculatorAlso in Terraform
- Terraform State Growth CalculatorAlso in Terraform
- Terraform Drift CalculatorAlso in Terraform