Terraform Lock Timeout Calculator

Calculate an appropriate state lock timeout based on team size and apply frequency.

About Terraform Lock Timeout Calculator

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

Worked example

With the default values below, Terraform Lock Timeout Calculator returns Recommended Lock Timeout of 16m. Change any input above and every figure here is recalculated in your browser.

Inputs used

Expected Apply Timeaccepts 0.1–100,000 minutes: 8 minutes
Safety Factoraccepts 1–20 ×: 2 ×
Concurrent Pipeline Runsaccepts 1–100,000 pipelines: 3 pipelines

Results

Recommended Lock Timeout: 16m min
Stale Lock Risk: Moderate
Worst-Case Queue Wait: 16m min
Total Worst-Case Wait: 32m min

Step by step

1Lock timeout: expected apply × safety factor= 16.0 min
2Worst-case queue wait (N-1 pipelines ahead)= 16.0 min

Assumptions and limits

The result is derived only from the 3 inputs listed above. Anything not among them is not part of the calculation.
In particular, this calculator does not take inflation, tax, fees or charges or compounding frequency into account.
Figures are rounded for display to 1 decimal place, so totals built from several rounded parts can differ slightly from the unrounded arithmetic.

How these calculators are built and tested is described on the Methodology page. If a figure looks wrong, please report it.

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.