Skip to content
Calcrivo

Terraform Lock Timeout Calculator

Calculate a safe state lock timeout from expected apply duration and flag stale lock risk.

Inputs

minutes

Typical time for `terraform apply` to complete on this configuration.

×

Multiplier applied to expected apply time to set the lock timeout.

pipelines

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

  1. Lock timeout: expected apply × safety factor

    8 × 2

    = 16.0 min

  2. 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