How to fix Error: Error acquiring the state lock in Terraform

TerraformINTERMEDIATEHIGHUpdated Dec 30, 2025· 170 views

Terraform state lock errors occur when Terraform cannot acquire an exclusive lock on your state file, usually due to concurrent operations, stale locks, or hung processes. This error prevents infrastructure changes and requires identifying and releasing the conflicting lock.

Quick fix

Fixes Error: Error acquiring the state lock

ps aux | grep terraform
  1. Identify the lock holder and verify no legitimate operations are running
  2. Force unlock using the lock ID from the error message
  3. Terminate hung processes if they still exist
  4. Verify backend permissions for remote backends
terraform — error
ps aux | grep terraform
Error: Error acquiring the state lock

What this error means

Terraform uses a pessimistic concurrency model that acquires an exclusive lock on the entire state file whenever an operation (plan, apply, or destroy) touches state. This global mutex ensures two processes never write to state simultaneously. When Terraform cannot acquire this lock—because another operation already holds it, the lock is stale, or permissions are insufficient—you get this error. The lock can be held by a hung process, a concurrent execution in CI/CD, network interruption aftermath, or permission restrictions in remote backends like Terraform Cloud.

Typical symptoms

  • Terraform plan or apply commands hang or fail immediately with "Error acquiring the state lock"
  • CI/CD pipelines fail intermittently during parallel executions
  • Lock ID appears in error messages showing which lock is held
  • No terraform operations complete until the lock is released
  • Team members are blocked from making infrastructure changes

Common causes

  1. Hung or zombie Terraform processes that never released their lock after interruption
  2. Concurrent terraform apply/plan operations targeting the same state file
  3. Network outages or interruptions that left locks in inconsistent state
  4. Stale locks from previous failed operations that were not cleaned up automatically
  5. Insufficient permissions to acquire locks in Terraform Cloud or remote backend
  6. Multiple CI/CD jobs triggered simultaneously without mutex protection
  7. Previous terraform operation crashed before releasing the lock

How to fix "Error: Error acquiring the state lock"

1Identify the lock holder and verify no legitimate operations are running

First, determine if another Terraform operation is legitimately in progress. Check with your team to see if someone is actively running terraform apply or plan. If you are the only one working, the lock is likely stale.

Check for hung Terraform processes on your machine:

bash
ps aux | grep terraform

If you find a hung process, note its PID for potential termination. In a team environment, coordinate with others before forcing a lock release.

2Force unlock using the lock ID from the error message

The error message contains a lock ID. Use terraform force-unlock to release it:

bash
terraform force-unlock LOCK_ID

For example:

bash
terraform force-unlock 6ff0f1f7-c0ac-4e61-8265-7d2bcce2b4ea

To skip the confirmation prompt:

bash
terraform force-unlock -force LOCK_ID

This removes the lock from your backend storage (S3, Azure, Consul, etc.) allowing new operations to proceed.

3Terminate hung processes if they still exist

If you identified a hung terraform process in step 1, terminate it:

bash
kill -9 PID

For example:

bash
kill -9 12345

On Windows, use:

powershell
Get-Process terraform | Stop-Process -Force

This prevents the process from continuing in the background and ensures the lock is truly abandoned.

4Verify backend permissions for remote backends

If using Terraform Cloud, AWS S3, Azure, or Consul, verify your authentication has proper permissions:

For Terraform Cloud:

bash
terraform login

Ensure the authenticated user belongs to:
- The owners team, OR
- Teams with "Manage all workspaces" permissions, OR
- Teams with "Project Admin" permissions for the specific project

For AWS S3/DynamoDB:

bash
aws sts get-caller-identity

Verify the returned user/role has s3:GetObject, s3:PutObject, and dynamodb:PutItem permissions on your backend resources.

For Azure Blob Storage:
Verify your storage account credentials and container access permissions are correct.

5For S3 backends, manually remove stale DynamoDB locks if force-unlock fails

If terraform force-unlock doesn't work with S3 backends, delete the lock directly from DynamoDB:

bash
aws dynamodb delete-item \
  --table-name terraform-state-lock \
  --key '{"LockID": {"S": "your-bucket/path/terraform.tfstate"}}' \
  --region us-east-1

Replace "your-bucket/path/terraform.tfstate" with your actual state path. This removes the stale lock entry from the DynamoDB lock table, allowing new lock acquisitions.

For Azure Blob Storage, locate and delete the .tflock file in your storage container:

bash
az storage blob delete \
  --account-name myaccount \
  --container-name mycontainer \
  --name path/to/terraform.tfstate.tflock
6Set up lock timeouts and CI/CD mutex protection to prevent recurrence

Prevent future state lock errors by using lock timeouts:

bash
terraform apply -lock-timeout=10m

Or in CI/CD pipelines:

bash
terraform init -lock=true -lock-timeout=120s

For CI/CD systems, implement mutex locks:

In GitHub Actions:

yaml
concurrency:
  group: terraform-state
  cancel-in-progress: false

In GitLab CI:

yaml
resource_group: terraform_state

In Azure DevOps or Jenkins, ensure only one pipeline job can run terraform against the same state file at a time. This prevents concurrent operations from even attempting simultaneous locking.

Advanced notes

State locking is not a bug—it's Terraform's safety mechanism. The "Error acquiring the state lock" means Terraform is working as designed: preventing concurrent writes to infrastructure state.

Lock timeouts in CI/CD: The -lock-timeout parameter tells Terraform to retry lock acquisition for the specified duration. Set it to 10-15 minutes in pipelines to handle brief network hiccups and allow other operations to complete naturally.

DynamoDB TTL: If using S3 backends, enable DynamoDB TTL on your lock table to automatically expire locks older than a threshold (e.g., 1 hour). This prevents truly orphaned locks from blocking operations forever.

Emergency bypass (last resort): terraform apply -lock=false bypasses locking entirely. Only use when absolutely certain no other operations are in progress. This is dangerous and can lead to corrupted state if multiple writes occur simultaneously.

Local state files: For local development, remove .terraform.tfstate.lock.info manually if a process crashed, but never do this in team/production environments without coordination.

Frequently asked questions

What does "Error: Error acquiring the state lock" mean?
Terraform uses a pessimistic concurrency model that acquires an exclusive lock on the entire state file whenever an operation (plan, apply, or destroy) touches state. This global mutex ensures two processes never write to state simultaneously. When Terraform cannot acquire this lock—because another operation already holds it, the lock is stale, or permissions are insufficient—you get this error.
How do I fix "Error: Error acquiring the state lock"?
Terraform state lock errors occur when Terraform cannot acquire an exclusive lock on your state file, usually due to concurrent operations, stale locks, or hung processes. This error prevents infrastructure changes and requires identifying and releasing the conflicting lock.
What causes "Error: Error acquiring the state lock"?
Hung or zombie Terraform processes that never released their lock after interruption Concurrent terraform apply/plan operations targeting the same state file Network outages or interruptions that left locks in inconsistent state
Is the "Error: Error acquiring the state lock" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading