Terraform "Error acquiring the state lock" - DynamoDB at init in CI

The S3 backend uses a DynamoDB table to serialize state writes. When Terraform cannot write the lock item - table missing, no permission, or a lock already held - the operation refuses to proceed.

What this error means

init (or the first plan after init) fails acquiring the state lock, naming the DynamoDB table and a ResourceNotFoundException or AccessDenied, or reporting the lock is already held.

Error: Error acquiring the state lock

Error message: operation error DynamoDB: PutItem, ResourceNotFoundException:
Requested resource not found
Lock Info:
  Path:      tf-state-prod/prod/terraform.tfstate
  Operation: OperationTypePlan

Common causes

Lock table does not exist

The dynamodb_table named in the backend was never created or is in another region.

No DynamoDB permission

The runner role lacks dynamodb:PutItem/GetItem/DeleteItem on the lock table.

Lock already held

A previous run crashed or a parallel job holds the lock, so the new run cannot acquire it.

How to fix it

Create or correct the lock table

Ensure the table exists in the backend region with a LockID (String) partition key.

aws dynamodb describe-table --table-name tf-locks --region us-east-1

Grant the lock-table permissions

1. Allow dynamodb:PutItem, GetItem, and DeleteItem on the table ARN.
2. Confirm region matches the table.
3. If a stale lock is held by a crashed run, use terraform force-unlock <ID> after confirming no run is active.

How to prevent it

• Provision the lock table with the state bucket in the same module.
• Serialize Terraform jobs per workspace to avoid concurrent lock contention.
• Alert on long-held locks so stale ones get cleared quickly.

Related guides