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

TerraformINTERMEDIATEHIGH

This error occurs when Terraform cannot acquire a lock on your state file, typically due to a previous incomplete operation or concurrent access. It happens most often with S3 backends using DynamoDB for state locking.

What this error means

Terraform uses state locking to prevent multiple processes from modifying the state file simultaneously, which could cause corruption. The ConditionalCheckFailedException error indicates that the conditional check for acquiring a lock failed—usually because another process already holds the lock or a previous operation was interrupted before releasing it. This is commonly seen when using S3 backends with DynamoDB for state management, where Terraform attempts to write a new lock record under the condition that one doesn't already exist.

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

1Verify no active Terraform processes are running

Before forcing an unlock, confirm that no Terraform operations are currently in progress. Check for hanging processes:

On Linux/Mac:

bash

ps aux | grep terraform

On Windows (PowerShell):

powershell

Get-Process terraform* -ErrorAction SilentlyContinue

If you find active processes, allow them to complete naturally. If they're hung, kill them only after confirming no one else is using Terraform:

bash

kill -9 <process_id>

2Use terraform force-unlock with the Lock ID

Terraform provides the Lock ID in the error message. Use this to force-unlock the state:

bash

terraform force-unlock <LOCK_ID>

Example:

bash

terraform force-unlock 49b6e22e-1234-5678-90ab-3e3097cf95d4

WARNING: Only force-unlock if you are absolutely certain no other process holds the lock. Forcing an unlock while another process is writing state will corrupt it.

3If force-unlock fails, check AWS IAM permissions

If you receive a permission error, verify your AWS IAM user has the required permissions for DynamoDB lock management:

json

{
  "Effect": "Allow",
  "Action": [
    "dynamodb:DescribeTable",
    "dynamodb:GetItem",
    "dynamodb:PutItem",
    "dynamodb:DeleteItem"
  ],
  "Resource": "arn:aws:dynamodb:*:*:table/terraform-locks"
}

Also ensure you have the correct S3 permissions for your state file:

json

{
  "Effect": "Allow",
  "Action": [
    "s3:GetObject",
    "s3:PutObject",
    "s3:DeleteObject"
  ],
  "Resource": "arn:aws:s3:::your-bucket/path/terraform.tfstate*"
}

4Manually remove the lock from DynamoDB (if needed)

If terraform force-unlock doesn't work, you can manually remove the lock from DynamoDB using the AWS CLI:

List current locks:

bash

aws dynamodb scan --table-name terraform-locks --region us-east-1

Delete a specific lock:

bash

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

Replace terraform-locks with your actual DynamoDB table name and update the S3 path accordingly.

5Retry your Terraform operation

After releasing the lock, retry your Terraform operation:

bash

terraform plan
terraform apply

Optionally, use a lock timeout to prevent this issue from repeating:

bash

terraform plan -lock-timeout=10m
terraform apply -lock-timeout=15m

This gives concurrent operations up to 10-15 minutes to complete before timing out.

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

What this error means

Typical symptoms

Common causes

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

Advanced notes

Related errors

Official resources & further reading