How to Use Terraform Force-Unlock to Fix a Locked State File

Ever found that your Terraform state file is ‘already locked’ when trying to perform a Terraform operation? In this article, we will look at the reasons why this might happen, and how to resolve this problem using the Terraform force-unlock command. We will explain what the command does, how to use it, the available options, and when you should use it.

1. What does Terraform force unlock do?
2. When should you use the force unlock command?
3. Where to find the lock ID?
4. Using Terraform force-unlock – example
5. Unlocking remote Terraform state
6. How to prevent Terraform state lock in the future

When you’re working with Terraform in a team or shared environment, multiple users or processes can attempt to modify the same state file simultaneously, which can lead to conflicting changes. To prevent conflicts and potential corruption of the state file, Terraform employs a locking mechanism. Without a lock, concurrent modifications could result in inconsistencies or race conditions, leading to incorrect provisioning or updates. By enforcing exclusive access, Terraform ensures that each modification is applied atomically.

Terraform’s force-unlock command is used to manually unlock a Terraform state that has been locked by another process. It allows you to release the lock manually regardless of the locking system’s state.

The syntax of the terraform force-unlock is as follows:

terraform force-unlock [options] LOCK_ID

The only available option for this command is to add -force, this won’t ask for input for unlock confirmation. The Lock ID can be found in the .tfstate.lock file, more information on how to inspect that below.

You should be cautious when using force-unlock, as it can lead to conflicts and inconsistencies if multiple processes are indeed trying to modify the state file simultaneously. It’s generally recommended to use it only when you’re certain that the lock is stuck or when you’re in a controlled environment where you can coordinate state file modifications effectively.

One of the most common causes of the state file becoming locked unexpectedly is a canceled or errored Terraform run. This could be because Terraform loses connection to the build agent It is running on. Therefore, Terraform acquires the lock but cannot contact the tfstate file to release it.

Another possible cause is that you are updating the storage account that holds the Terraform state file, which makes it unreachable. For example, in the case of using a storage account hosted in Azure, adding a private endpoint, modifying the firewall or ACLs, or permissions on the account. In these situations, another way of breaking the lock is to navigate to the state file itself and check the lease status of the blob. In a situation where the state file is locked, the file will show as ‘leased’, in which case to you should select ‘break lease’ to release the lock.

The lock file contains the lock ID along with other metadata about the lock. The location of the lock file depends on the backend being used to store the Terraform state. To find the lock ID, you need to inspect the lock file or use the appropriate tooling provided by the backend service.

If you’re using the local backend, the lock file is typically stored alongside the state file with the suffix .tfstate.lock. If you’re using a remote backend like S3 or Azure Blob Storage, the lock file is stored within the backend itself. You can download and inspect the lock file locally to find the lock ID.

If you’re using the Consul backend, the lock ID is stored within the Consul key-value store, and you would typically access it using Consul’s APIs or CLI tools. To use the CLI method, use the consul kv command to list the keys stored in Consul. The lock IDs should be stored under a specific key path related to your Terraform state.

consul kv get <key_path>

You can also make an HTTP GET request to Consul’s key-value store API endpoint to retrieve the lock file contents.

• curl -X GET http://<consul_address>/v1/kv/<key_path>?recurse

Replace <consul_address> with the address of your Consul server and <key_path> with the path where your Terraform state lock file is stored. The output of the API call will be in JSON format. You’ll need to parse it to find the lock ID. Each entry in the response corresponds to a key-value pair stored in Consul.

Let’s go through the steps:

Step 1: Identify the lock error

The most common way you will discover a locked state is by running a Terraform command such as terraform apply or terraform plan and receiving an error similar to the following:

Error: Error acquiring the state lock

Error message: ConditionalCheckFailedException: The conditional request failed

Lock Info:
  ID:        b8814894-4a5f-217b-e97b-c4f5c02a1f88
  Path:      terraform-state/prod/terraform.tfstate
  Operation: OperationTypeApply
  Who:       user@build-agent-01
  Version:   1.7.0
  Created:   2024-04-01 09:15:00.000000 +0000 UTC
  Info:

Terraform acquires a state lock to protect the state from being written
by multiple users at the same time. Please resolve the issue above and
try again. For most commands, you can disable locking with the
"-lock=false" flag, but this is not recommended.

The ID field in this error output is the lock ID you will need for the force-unlock command. The Who field shows which user or build agent held the lock, and Created shows when the lock was acquired. Take note of these before proceeding, as they help you confirm whether the locking process is genuinely no longer running.

Step 2: Confirm the lock is genuinely stuck

Before running force-unlock, verify that no other Terraform process is actively using the state. If you force-unlock a state that is legitimately held by a running operation, you risk two processes writing to the state at the same time, which can cause corruption.

Check the following:

• Look at the Who field in the lock error. If it points to a CI/CD pipeline, check the pipeline’s status in your CI/CD tool to confirm the run has ended.
• If the lock was created very recently, wait a few minutes to rule out a slow but still-active operation.
• If the lock was created by another team member, confirm with them directly that their run has finished or failed before proceeding.

Step 3: Navigate to your Terraform configuration directory

Before running the command, change into the directory that contains your Terraform configuration files (main.tf, variables.tf, etc.). This ensures Terraform can locate the correct backend configuration and targets the right state file.

cd /path/to/your/terraform/project

Step 4: Run the force-unlock command

Run terraform force-unlock with the lock ID from the error message:

terraform force-unlock b8814894-4a5f-217b-e97b-c4f5c02a1f88

By default, Terraform will prompt you to confirm the operation before proceeding:

Do you really want to force-unlock?
  Terraform will remove the lock on the remote state.
  This will allow local Terraform commands to modify this state, even though it
  may still be in use. Only 'yes' will be accepted to confirm.

  Enter a value:

Type yes and press Enter to release the lock. If successful, Terraform will confirm:

Terraform state has been successfully unlocked!

Using the -force flag

If you want to skip the interactive confirmation prompt entirely, for example in an automated script or CI/CD pipeline, add the -force flag:

terraform force-unlock -force b8814894-4a5f-217b-e97b-c4f5c02a1f88

This will release the lock immediately without asking for input. Use this option with caution and only in situations where you have already confirmed the state is safe to unlock.

Important: The force-unlock command does not modify your infrastructure. It only removes the lock entry from the backend. No resources are created, changed, or destroyed as a result of running this command.

Step 5: Verify the state is consistent

After unlocking, run terraform plan to verify that the state is consistent and that no partial changes were left behind by the interrupted operation:

terraform plan

Review the plan output carefully. If the plan shows unexpected changes, the previous operation may have partially completed before it was interrupted. In that case, review the state carefully and consider running terraform apply only after confirming that the planned changes are correct.

Other options to unlock remote Terraform state:

• Delete the lock file from the backend storage to release the lock entirely.
• Edit the lock file to remove the lock information, effectively releasing the lock.

Attempt to run a Terraform command that requires a lock, such as terraform apply, to verify that the lock has been released. You should also ensure that no other processes are modifying the Terraform state while it’s unlocked. Coordinate with your team to prevent conflicts.

While force-unlock is a useful recovery tool, the goal should be to avoid getting into a stuck lock situation in the first place. The following practices will reduce how often you encounter state lock errors.

• Use a locking-capable remote backend – Always use a remote backend that supports state locking, such as S3 with DynamoDB, Azure Blob Storage, or Google Cloud Storage. Local state files offer no coordination between team members and cannot be unlocked by another process.
• Never cancel a running Terraform operation – The most common cause of a stuck lock is a run interrupted before it could release the lock cleanly. Allow terraform apply or terraform plan to complete or fail naturally, then confirm the lock was released before starting another run.
• Isolate workspaces by environment – Use separate Terraform workspaces or state files per environment (for example, dev, staging, prod). This limits a stuck lock to a single environment and prevents one team’s work from blocking another.
• Coordinate runs through a single pipeline – Avoid running Terraform locally against shared remote state while a CI/CD pipeline is also targeting the same state. Route all runs through a single, trusted pipeline so that only one operation can acquire the lock at a time.
• Use a Terraform management platform – Tools like Spacelift manage the run queue automatically, ensuring only one operation runs against a given stack at a time. Spacelift also provides full visibility into run history, making it easy to identify which run caused a stuck lock and resolve it quickly.

Terraform uses a lock on the state file to prevent concurrent modifications that could lead to conflicts or data corruption.

force-unlock should be used only when necessary, as it can lead to data corruption or conflicts if multiple processes are modifying the state simultaneously. Always ensure that you have appropriate permissions and understand the implications before using force-unlock.

If you are interested in learning more about Spacelift, create a free account today or book a demo with one of our engineers.

Note: New versions of Terraform will be placed under the BUSL license, but everything created before version 1.5.x stays open-source. OpenTofu is an open-source version of Terraform that will expand on Terraform’s existing concepts and offerings. It is a viable alternative to HashiCorp’s Terraform, being forked from Terraform version 1.5.6.