Terraform State Lock Error — State File Locked by Another Process

Fix Terraform state lock errors when another process holds the lock on the state file, preventing plan, apply, or destroy operations. This guide covers everything you need to know about this topic, including common causes, step-by-step solutions, and answers to frequently asked questions.

Here are the key things to understand: Terraform locks the state file during write operations to prevent concurrent modifications. State locking prevents two terraform apply commands from running simultaneously on the same state. Remote backends (S3+DynamoDB, Terraform Cloud, GCS) provide distributed locking. Lock information includes: who locked it, when, and which operation. A stuck lock usually means a previous Terraform process crashed without releasing the lock. Understanding these fundamentals will help you diagnose and resolve this issue more effectively.

The most common reasons this occurs include: Previous terraform apply or plan was interrupted (Ctrl+C, crash, network disconnect). Another team member is running Terraform against the same state file simultaneously. CI/CD pipeline hung or timed out while holding the state lock. DynamoDB lock table (for S3 backend) has a stale lock entry. Identifying the root cause is the first step toward finding the right solution.

To resolve this, follow these recommended steps: Check if another Terraform process is actually running — do not force unlock if it is. Force unlock the state: 'terraform force-unlock LOCK_ID' (use the lock ID from the error message). For S3+DynamoDB backend: check the DynamoDB lock table for stale entries and delete manually if needed. For Terraform Cloud: check the workspace runs page for stuck runs and cancel them. Prevent future issues: use CI/CD pipelines with proper timeouts and ensure only one pipeline runs at a time. If these steps do not resolve the issue, consider consulting additional resources or a qualified professional.

This article is part of our Linux Error Codes collection on Error Codes Wiki. We provide comprehensive, up-to-date information to help you find solutions quickly.