Failed to unlock state: lock ID does not match existing lock ID

Problem

When attempting to unlock a remote backend workspace from the Terraform CLI, the operation fails with the following error message:

Failed to unlock state: lock ID "f51f0d55-84a8-cfae-6217-e3e0046397c1" does not match existing lock ID

Prerequisites

• HCP Terraform
• Terraform Enterprise

Cause

Unlocking remote backend workspaces directly from the Terraform CLI is not a supported operation. This is the default behavior for workspaces managed by HCP Terraform or Terraform Enterprise, and the lock must be removed using the UI or API.

Solutions

There are three methods to unlock a workspace.

Solution 1: Unlock via the UI

You can unlock the workspace directly from the HCP Terraform or Terraform Enterprise web interface. This requires a user account with at least "Manage Workspaces" permissions.

1. Log in to the HCP Terraform or Terraform Enterprise UI.
2. Select the organization where the workspace resides.
3. Click on the name of the locked workspace.
4. From the Settings dropdown menu, select Locking.
5. Click the Unlock button and confirm the action.

Solution 2: Unlock via the API

You can use the API to programmatically unlock the workspace.

1. Retrieve the workspace ID. For HCP Terraform, the hostname is app.terraform.io.

   $ curl \
     --header "Authorization: Bearer $TOKEN" \
     --header "Content-Type: application/vnd.api+json" \
     https://$TFE_HOSTNAME/api/v2/organizations/$YOUR_ORG/workspaces/$YOUR_WORKSPACE | jq -r '.data.id'

2. Use the workspace ID from the previous step to unlock the workspace.

   $ curl \
     --header "Authorization: Bearer $TOKEN" \
     --header "Content-Type: application/vnd.api+json" \
     --request POST \
     https://$TFE_HOSTNAME/api/v2/workspaces/$WORKSPACE_ID/actions/unlock

Solution 3: Unlock via the Rails Console (Terraform Enterprise Only)

If you are unable to unlock the workspace using the UI or API, Terraform Enterprise administrators can use the Rails console.

1. Log in to the Terraform Enterprise instance via SSH.

2. Launch the Rails console. Note that on older Terraform Enterprise installations, the container name may be ptfe_atlas instead of tfe-atlas.

   # docker exec -ti tfe-atlas /usr/bin/init.sh /app/scripts/wait-for-token -- bash -ic 'cd /app && bin/rails c'

3. Once the Rails console has loaded, run the following commands to find the workspace by name and unlock it.

   ws = Workspace.find_by(name: "workspace_name")
   ws.unlock!
   ws.save

Outcome

After a successful unlock, the padlock icon next to the workspace name in the UI will disappear. You will then be able to trigger runs from the CLI for that workspace.

Additional Information

• How to Access the Terraform Enterprise Rails Console.
• Create a local TFE Administrator through the Rails Console.
• Restoring Site-Admin Access when No Accounts have Access.