Terraform state lock conflict

What this failure means

Terraform could not acquire the state lock because another Terraform process is currently holding it. Only one Terraform operation can modify a given state at a time.

Symptoms

Faultline looks for one or more of these log fragments:

error locking state
state lock
lock id
another terraform process
terraform state is locked
error acquiring the state lock

Diagnosis

Terraform could not acquire the state lock because another Terraform process is currently holding it. Only one Terraform operation can modify a given state at a time.

State locking prevents concurrent modifications to the same infrastructure. The lock is usually held by a parallel CI job, a manual run, or a crashed previous job that did not release the lock.

Fix steps

1. Identify which job or operator currently holds the lock before taking action. The backend usually records the lock ID and owner context.
2. Wait for any active Terraform plan or apply touching the same state to complete, or cancel the duplicate run in CI.
3. Use terraform force-unlock <LOCK_ID> only after confirming the lock is stale and no active Terraform process is still working against that state.
4. Check your CI configuration for parallel jobs, retries, or manual approval paths that target the same Terraform backend or workspace.

Validation

• Re-run the Terraform command after the active lock holder exits or the stale lock is cleared.
• Confirm Terraform acquires the lock cleanly and proceeds without a state-lock error.

Why it matters

Terraform state locking protects shared infrastructure from concurrent writes. Bypassing the lock incorrectly can corrupt state or hide overlapping deploy activity.

Prevention

• Serialize Terraform runs per environment using CI concurrency groups, environment locks, or a single deployment lane.
• Use separate state files or workspaces for environments that are expected to run in parallel.
• Alert on locks that outlive the normal apply window so stale-state incidents are caught quickly.

Try it locally

terraform plan
terraform plan

How Faultline detects it

Use faultline explain terraform-state-lock to see the full playbook.

faultline analyze build.log
faultline explain terraform-state-lock

Generated from playbooks/bundled/log/deploy/terraform-state-lock.yaml. Do not edit directly.