Terraform Force-Unlock Command : Unlocking TF State File

Ever found 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

When you’re working with Terraform in a team or in a shared environment, it’s possible for multiple users or processes to attempt to modify the same state file simultaneously, and therefore a risk of 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, disregarding the state of the locking system.

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

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 would be if you are updating the storage account using Terraform that holds the Terraform state file, which causes it to be 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 ‘brake 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.

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:

1. First, identify the lock ID. This can typically be found within the lock file or through the locking system you’re using. Let’s say the lock ID is b8814894-4a5f-217b-e97b-c4f5c02a1f88.
2. Navigate to the directory containing your Terraform configuration files (main.tf, variables.tf, etc.).
3. Run the terraform force-unlock command with the lock ID:

This command will release the lock associated with the specified lock ID. If successful, Terraform will output a message indicating that the lock has been released.

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.

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.

We encourage you also to explore how Spacelift makes it easy to work with Terraform. Spacelift can optionally manage the Terraform state for you, offering a backend synchronized with the rest of the platform to maximize convenience and security. You also get the ability to import your state during stack creation, which is very useful for engineers who are migrating their old configurations and states to Spacelift.

At the same time, it’s protected against accidental or malicious access as Spacelift is able to map state access and changes to legitimate Spacelift runs, automatically blocking all unauthorized traffic.

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.