Terraform — Error acquiring the state lock

Resolve Terraform state lock errors by confirming no run is active and force-unlocking only when safe.

intermediatedebuggingterraformstate

Symptoms

Error acquiring the state lock
A lock ID is shown from a previous run
apply fails after a crash or interruption
A teammate holds the lock from another machine

Possible causes

Another Terraform run holds the lock
A previous run crashed and left the lock behind
The remote backend lock was not released on interruption
Two CI jobs run concurrently against the same state

Diagnosis steps

Read the lock ID, who and when

terraform plan 2>&1 | head -20

Interpretation

The error names the lock ID, the user and the time, showing whether the holder is active or a stale leftover.

Confirm no run is active

terraform force-unlock <LOCK_ID>

Interpretation

Force-unlocking a genuinely stale lock clears it; force-unlocking an active run risks two writers on the same state.

Inspect the backend lock directly

terraform state pull | head

Interpretation

Reading state can reveal whether the backend is reachable and whether the lock object points at a dead run.

Root cause

The state backend held a lock from an active or stale run, so Terraform refused to proceed to prevent two runs from modifying the same state concurrently.

Fix

Wait for the active run to finish or coordinate with the holder, and use force-unlock with the exact lock ID only when you have confirmed no run is in progress.

Verify the fix

Run plan again and confirm it acquires the lock and proceeds, and confirm the remote lock object is gone.

Symptom walkthrough

Plan or apply fails with Error acquiring the state lock and prints a lock ID along with who acquired it and when. This is the backend protecting state from concurrent modification. The lock may be held by an active teammate or CI run, or left behind by one that crashed, and the distinction matters because force-unlocking an active run can corrupt state.

Fix in practice

Check whether the named holder is still running and wait or coordinate if so. Only when you have confirmed the run is dead should you force-unlock with the exact lock ID. Prevent recurrence by serializing CI runs and ensuring interrupted runs release the lock.

Verification

Run plan again and confirm it acquires the lock and proceeds, then confirm the lock object is gone from the backend. A clean acquisition confirms the stale lock is cleared.

Diagnostic commands

Check the behavior with commands like these:

terraform plan 2>&1 | head -20
terraform force-unlock <LOCK_ID>
terraform state pull | head