In distributed infrastructure engineering, Terraform state locking is an essential pessimistic concurrency guardrail. Without state locking, two parallel executions of terraform apply could write conflicting resources to the cloud provider, corrupting the JSON state file and leaving unmanaged infrastructure running untracked.

However, when a CI/CD job crashes, a runner VM is terminated by an autoscaler, or an engineer disconnects during a local run, the lock record remains active in the backend storage. Every subsequent plan or apply immediately fails.


1. Symptom & Exact Error Output

When state locking prevents command execution, Terraform or OpenTofu outputs a structured error block containing the lock metadata:

Error: Error acquiring the state lock

Error message: ConditionalCheckFailedException: The conditional request failed
Lock Info:
  ID:        d3b07384-d113-4856-9d3e-9086cf748d59
  Path:      production-tf-state/infrastructure/terraform.tfstate
  Operation: OperationTypeApply
  Who:       runner-42@ip-10-0-14-122
  Version:   1.9.4
  Created:   2026-11-17 11:22:45.319401 +0000 UTC
  Info:      

This message tells you five critical diagnostic facts:

  • ID: The unique UUID assigned to this locking transaction.
  • Path: The exact state file path in your S3 bucket or backend storage.
  • Operation: The command that acquired the lock (typically OperationTypePlan or OperationTypeApply).
  • Who: The username and hostname that dialed the backend.
  • Created: The exact timestamp when the lock was established.

2. Quick 60-Second Triage Decision Matrix

Before typing any unlock command, walk through this 3-step decision tree:

State Lock Triage Decision Tree

  1. Is a CI/CD pipeline actively running? Inspect GitHub Actions, GitLab CI, or Jenkins. If a pipeline job targeting this workspace is currently in Running status, DO NOT UNLOCK. The lock is legitimate. Wait for the pipeline to finish.
  2. Did the runner terminate unexpectedly? If the CI/CD job timed out, was cancelled, or the spot runner was evicted, the lock is orphaned and safe to clear.
  3. Was the lock created hours or days ago? If the Created timestamp is significantly older than your organization’s longest CI/CD timeout (e.g., created 3 hours ago for a 15-minute pipeline), it is definitively stale.
Production Warning: Breaking a lock while another process is actively creating, modifying, or destroying cloud infrastructure can corrupt your remote state file or cause dual simultaneous writes. Always verify that no active runner process exists.

3. Safe Read-Only Inspection Commands

For backends backed by AWS S3 and DynamoDB, Terraform stores the lock as an item in the DynamoDB table configured in your backend block:

# Inspect the lock record in DynamoDB without mutating state
aws dynamodb get-item \
  --table-name "terraform-state-locks" \
  --key '{"LockID": {"S": "production-tf-state/infrastructure/terraform.tfstate-md5"}}' \
  --region us-east-1

The returned DynamoDB record contains the full JSON string inside the Info attribute, including the host PID, user, and execution ID. Compare this PID and hostname against your active server instances.


4. Resolution Procedure: Step-by-Step

Method 1: Standard CLI Force-Unlock (Recommended)

Once you have verified that the runner process is deceased, copy the exact ID string from the error message and run:

terraform force-unlock d3b07384-d113-4856-9d3e-9086cf748d59

Terraform will prompt for manual confirmation:

Do you really want to force-unlock?
  Terraform will remove the lock on the remote state.
  This will allow local and remote processes to write to the state.
  This could lead to state corruption if other processes are currently writing.

  Enter a value: yes

Terraform state has been successfully unlocked!

Method 2: Manual DynamoDB Item Eviction (Emergency Fallback)

In rare edge cases (e.g., when your local Terraform configuration is in an un-parseable state or credentials prevent CLI backend initialization), you can delete the stale lock item directly in DynamoDB:

# Emergency manual eviction of orphaned lock item
aws dynamodb delete-item \
  --table-name "terraform-state-locks" \
  --key '{"LockID": {"S": "production-tf-state/infrastructure/terraform.tfstate-md5"}}' \
  --region us-east-1

Method 3: Local Backend File Cleanup

If you are working on a sandbox module using the local filesystem backend, Terraform creates a hidden lock file alongside your state. If the process crashed, remove the orphaned lock info file:

# Only for local state backends!
rm -f .terraform.tfstate.lock.info

5. Verification & Safe State Validation

After unlocking, verify that the remote state is uncorrupted and that your backend can acquire and release locks cleanly:

  1. Run a non-mutating plan operation:
    terraform plan -lock-timeout=30s
  2. Confirm that Terraform successfully acquires the lock, refreshes the provider state, prints the plan output, and releases the lock without errors.
  3. Inspect S3 versioning history to ensure no unexpected empty state was uploaded:
    aws s3api list-object-versions \
      --bucket "production-tf-state" \
      --prefix "infrastructure/terraform.tfstate" \
      --max-items 5

6. Prevention: Hardening CI/CD Against Stale Locks

To eliminate 95% of state lock issues in platform engineering workflows, implement these three pipeline patterns:

Pattern A: Configure Lock Timeouts

By default, Terraform fails instantly if a lock cannot be acquired. In CI/CD pipelines where another job might be finishing up, add -lock-timeout to give the prior job a reasonable grace period to release:

terraform apply -lock-timeout=10m -auto-approve

Pattern B: Enforce Pipeline Concurrency Groups

In GitHub Actions, use concurrency groups tied to your environment or state file path. This queues parallel commits rather than allowing them to collide and compete for the DynamoDB lock:

# .github/workflows/terraform.yml
name: Terraform Deploy
on:
  push:
    branches: [main]

concurrency:
  group: terraform-production-lock
  cancel-in-progress: false

Pattern C: Prohibit Local Applies to Shared Environments

Enforce through IAM policies that only CI/CD assumed roles (via OIDC) possess dynamodb:PutItem and dynamodb:DeleteItem permissions on production lock tables. Individual engineers should only possess read access (terraform plan), preventing developer laptops from leaving orphaned locks when their Wi-Fi drops.


7. Related Runbooks & Architecture Guides