Interactive Troubleshooter

Published: Sep 4, 2026

Terraform Apply Failed: State Lock and Errors

Time: 15 mins Level: Beginner

By StepDiag Engineering Team

Reviewed by Ibraheem Taofeeq Opeyemi

An exhaustive interactive diagnostic guide to fix Terraform apply failures, state lock acquisition errors, and provider authentication drops. Follow structured troubleshooting paths for DynamoDB state unlock, IAM permission gaps, and resource drift.

Full Diagnostic Tree & Step-by-Step Overview

What specific error message or failure mode occurs when executing 'terraform apply'?

Error acquiring the state lock: Lock Info ID or DynamoDB lock table timeout.
Cloud provider authentication failure, 403 Access Denied, or expired credentials.
'Resource already exists' conflict, state drift, or cyclical dependency error.
Provider checksum lockfile mismatch (.terraform.lock.hcl) or plugin initialization failure.

What caused or accompanied the state lock acquisition failure?

A previous Terraform run crashed, timed out, or was interrupted manually, leaving a stale lock ID.
A concurrent CI/CD job or team member is running Terraform against the same state simultaneously.
Terraform fails to write to the DynamoDB lock table or S3 state bucket due to missing IAM permissions.

Force-Unlock Stale Remote State Lock ID

Solution:

Root Cause: Stale Lock Registration from Interrupted Execution

When Terraform begins an operation against a remote backend (such as AWS S3 with DynamoDB, Terraform Cloud, or Azure Blob Storage), it writes a lock record containing a unique Lock ID, process ID, host, and timestamp. If the CLI process crashes, loses network connectivity, or is forcefully killed (SIGKILL / Ctrl+C), the lock record remains in the state database, blocking future executions.

Step-by-Step Fix:

1Identify the Stale Lock ID:

Review the terminal output from terraform apply to locate the exact Lock ID string:

text
     Error: Error acquiring the state lock
     Lock Info:
       ID:        e1a23b45-6789-0123-4567-89abcdef0123
       Path:      my-bucket/terraform.tfstate
       Operation: OperationTypeApply
       Who:       user@dev-machine
       Created:   2026-09-04 10:15:00 UTC

2Verify Process Termination:

Confirm that the process owner listed under Who is not actively running Terraform on another machine or CI worker.

3Execute Force-Unlock Command:

Run the unlock command using the extracted Lock ID:

bash
     terraform force-unlock e1a23b45-6789-0123-4567-89abcdef0123

Type yes when prompted to confirm unlocking.

4Fallback Manual Unlock (AWS DynamoDB):

If force-unlock fails due to backend sync issues, navigate to the AWS DynamoDB Console.

Locate the state lock table (e.g., terraform-state-locks).

Search for item with LockID matching my-bucket/terraform.tfstate-md5 and delete the item record.

Synchronize CI/CD Pipeline Executions & Workspace Isolation

Solution:

Root Cause: Concurrent Write Contention Across CI/CD Workers

Multiple automated CI/CD pipeline workers (e.g., GitHub Actions, GitLab CI, Jenkins) or team members executing terraform apply simultaneously against the same workspace cause state lock collision. Remote backends enforce mutex locking to prevent catastrophic state corruption caused by concurrent updates.

Step-by-Step Fix:

1Enable Concurrency Limits in CI/CD Pipelines:

In GitHub Actions, configure workflow concurrency groups to serialize runs per workspace:

yaml
     concurrency:
       group: terraform-${{ github.ref }}
       cancel-in-progress: false

In GitLab CI, set resource_group: production_terraform to serialize job queues.

2Isolate Workspaces and State Paths:

Ensure separate environments (Dev, Staging, Prod) use distinct state key paths or separate Terraform workspaces:

bash
     terraform workspace select production || terraform workspace new production

3Use Non-Blocking Plan Steps:

Run terraform plan -lock=true during PR checks, and only acquire full apply locks in locked deployment stages.

Grant Required State Backend & Lock Table IAM Permissions

Solution:

Root Cause: Insufficient IAM Policies for DynamoDB / Storage Backend State Locking

To manage state locking, Terraform requires read/write permissions not only on the primary state storage container (e.g., S3 bucket or Azure Blob Container) but also on the key-value locking mechanism (e.g., AWS DynamoDB table or Azure Lease Blob). Missing dynamodb:PutItem, GetItem, or DeleteItem privileges cause immediate state lock initialization failures.

Step-by-Step Fix:

1Verify AWS IAM Policy for S3 + DynamoDB Backend:

Ensure the active IAM user, role, or CI runner policy includes both S3 and DynamoDB actions:

json
     {
       "Version": "2012-10-17",
       "Statement": [
         {
           "Effect": "Allow",
           "Action": [
             "s3:GetObject",
             "s3:PutObject",
             "s3:ListBucket"
           ],
           "Resource": [
             "arn:aws:s3:::my-tf-state-bucket",
             "arn:aws:s3:::my-tf-state-bucket/*"
           ]
         },
         {
           "Effect": "Allow",
           "Action": [
             "dynamodb:GetItem",
             "dynamodb:PutItem",
             "dynamodb:DeleteItem"
           ],
           "Resource": "arn:aws:dynamodb:*:*:table/terraform-state-locks"
         }
       ]
     }

2Review Backend Definition in HCL:

Verify backend block syntax in backend.tf:

hcl
     terraform {
       backend "s3" {
         bucket         = "my-tf-state-bucket"
         key            = "global/s3/terraform.tfstate"
         region         = "us-east-1"
         dynamodb_table = "terraform-state-locks"
         encrypt        = true
       }
     }

How is the cloud provider authentication or access failure presenting itself?

Expired cloud session credentials, invalid STS tokens, or unconfigured environment variables.
Specific API call returns 'AccessDenied', 403 Forbidden, or missing IAM permission for a resource.

Refresh Expired Provider Credentials & STS Session Tokens

Solution:

Root Cause: Expired Security Credentials or Misconfigured CLI Profiles

Terraform relies on cloud SDK provider plugins (e.g., hashicorp/aws, hashicorp/azurerm) to authenticate requests. When temporary session credentials (such as AWS STS tokens, Okta/SSO sessions, or Azure Service Principals) expire during or before plan/apply, the provider cannot sign API requests, causing immediate execution termination.

Step-by-Step Fix:

1Re-Authenticate Cloud CLI Sessions:

For AWS SSO / IAM Identity Center:

bash
     aws sso login --profile my-profile
     export AWS_PROFILE="my-profile"

For Azure CLI:

bash
     az login
     az account set --subscription "<subscription-id>"

For GCP:

bash
     gcloud auth application-default login

2Verify Environment Variable Order of Precedence:

Clear stale static environment variables that may override profile configs:

bash
     unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN

3Test Identity with Cloud CLI:

Verify active identity before re-running apply: aws sts get-caller-identity.

Remediate Missing IAM Permissions for Cloud Resource Creation

Solution:

Root Cause: Principle of Least Privilege Blocking Resource Mutation

Even with valid authentication, the executing IAM principal may lack permission to create, modify, or inspect specific target resources (e.g., ec2:RunInstances, s3:CreateBucket, or iam:CreateRole). Refer to the HashiCorp Official Terraform Documentation for detailed backend and provider configuration specifications.

Step-by-Step Fix:

1Identify Failed API Calls from Trace Logs:

Enable verbose logging to isolate the exact API action and resource Amazon Resource Name (ARN):

bash
     export TF_LOG=DEBUG
     terraform apply 2>&1 | grep -i "AccessDenied"

2Update IAM Role / Service Principal Policies:

Add the required API actions to the executing IAM role or policy attached to your user/pipeline.

For AWS IAM permission boundaries, ensure the boundary policy explicitly permits the requested action.

3Verify Provider Impersonation / AssumeRole Blocks:

If using assume_role in your provider block, verify trust relationships allow the source principal to assume the destination role:

hcl
     provider "aws" {
       region = "us-east-1"
       assume_role {
         role_arn     = "arn:aws:iam::123456789012:role/TerraformDeploymentRole"
         session_name = "TerraformSession"
       }
     }

What type of state drift, conflict, or graph topology error occurred?

Terraform fails with 'Resource already exists' because infrastructure was manually created in cloud GUI.
Terraform fails with 'Cycle:' error indicating cyclical resource dependencies.

Import Existing Infrastructure into Terraform State

Solution:

Root Cause: Unmanaged Infrastructure Collision (Out-of-Band Creation)

When a resource exists in the real cloud environment (e.g., an S3 bucket or Security Group created manually in the cloud console) but does not exist in the .tfstate file, Terraform attempts to create it anew. The cloud API rejects the request with a duplicate resource error.

Step-by-Step Fix:

1Option A: Declare an import Block (Terraform v1.5+):

Add an explicit import block to your HCL code:

hcl
     import {
       to = aws_s3_bucket.my_bucket
       id = "existing-bucket-name"
     }

Run terraform plan to automatically generate or verify the configuration import.

2Option B: Execute terraform import CLI Command:

Import the resource ID directly into your state graph:

bash
     terraform import aws_s3_bucket.my_bucket existing-bucket-name

3Reconcile Configuration and Apply:

Run terraform plan to ensure zero drift between the local code definition and the imported live state, then proceed with terraform apply.

Break Cyclical Resource Dependencies in HCL Graph

Solution:

Root Cause: Circular Reference Topology in Resource Attributes

Terraform constructs a Directed Acyclic Graph (DAG) to determine the exact order in which resources must be created or updated. If Resource A references an output attribute of Resource B, while Resource B simultaneously references an output attribute of Resource A, Terraform cannot calculate an execution graph, throwing a Cycle: error.

Step-by-Step Fix:

1Identify the Dependency Loop from Error Output:

Examine the graph loop provided in the console output:

text
     Error: Cycle: aws_security_group.sg_a, aws_security_group_rule.rule_b, aws_security_group.sg_b

2Decouple Inline Rules or Attachments:

Instead of declaring security group rules inline inside aws_security_group blocks, move them to standalone aws_security_group_rule resource blocks.

3Remove Implicit and Explicit depends_on Loops:

Inspect resource blocks for unnecessary depends_on meta-arguments or circular interpolation references.

4Visualize Execution Graph:

Generate and inspect the DAG structure visually to locate unintended links:

bash
     terraform graph | dot -Tsvg > graph.svg

What provider lockfile or backend plugin error was encountered?

Provider checksum error or platform lock mismatch in '.terraform.lock.hcl'.
Backend state migration error or provider plugin initialization failure during init/apply.

Reconcile Provider Lockfile Checksums Across Operating Platforms

Solution:

Root Cause: Platform Architecture Hash Mismatch in `.terraform.lock.hcl`

The .terraform.lock.hcl dependency lockfile records cryptographic checksum hashes (h1: and zh:) for provider binaries. If a developer generates the lockfile on macOS (ARM64) and commits it to Git, and a CI runner on Linux (AMD64) attempts to run terraform init or apply, the runner rejects the provider binaries if their OS platform hashes are absent from the lockfile.

Step-by-Step Fix:

1Update Lockfile with Multi-Platform Hashes:

Cross-compile and append missing target platform checksums to .terraform.lock.hcl without downloading binaries:

bash
     terraform providers lock \
       -platform=linux_amd64 \
       -platform=darwin_arm64 \
       -platform=windows_amd64

2Upgrade Provider Version Signatures:

If updating provider versions, force lockfile regeneration:

bash
     terraform init -upgrade

3Commit Updated Lockfile:

Ensure .terraform.lock.hcl is tracked in version control (Git) so team members and CI pipelines maintain deterministic provider environments.

Re-initialize State Backend and Clear Stale Plugin Caches

Solution:

Root Cause: Corrupted Local `.terraform` Directory or Migration State Mismatch

When switching branches, updating backend configurations, or upgrading Terraform binary versions, the cached provider plugins and backend state pointers in the hidden local .terraform directory can become corrupt or out of sync with the current HCL code.

Step-by-Step Fix:

1Remove Local .terraform Cache Directory:

Purge local working state cache (this does NOT delete your remote infrastructure or remote state file):

bash
     rm -rf .terraform .terraform.lock.hcl

2Re-initialize Backend Connection:

Re-download required providers and re-establish backend configuration:

bash
     terraform init -reconfigure

3Handle Backend Migration (If Migrating State):

If intentionally changing backends (e.g., from local to S3), run:

bash
     terraform init -migrate-state

Related Diagnostic Guides

Windows Update Error 0x80070002 Missing Files Diagnostic Guide

System Restore Failed 0x80070005 Antivirus Conflict Tree

Windows Photo Viewer Not Showing Thumbnails: Codec Diagnostic

Safe Mode Password Not Working With Microsoft Account Fix

Clipboard History Not Working Windows 11: Sync Service Tree

Subscribe to StepDiag

Embed Guide on Your Website