How to unlock workspace in TFE or fix false-corrupted workspace that is crashing UI

Problem

A Terraform Enterprise (TFE) workspace may appear on the overview page but becomes unresponsive or crashes the UI with an HTTP error 500 when selected. API queries for the workspace name or ID fail to find it. In TFE logs, you may see a SIC-0001 error without a clear cause.

Cause

This issue can occur when a network connection is interrupted while TFE saves the workspace state. The lock is not fully written, leaving the workspace in a partially locked, corrupted state that the UI cannot handle correctly.

Solution

This procedure force-unlocks the workspace using the TFE Rails console.

Note on TFE Container Naming

For TFE versions v202205-1 through v202308-1, container names use the tfe-<service> convention (e.g., tfe-atlas). Older versions may use the ptfe_ prefix (e.g., ptfe_atlas). Adjust the commands in this guide to match your TFE version's container naming scheme. You can find more information in the v202205-1 release notes.

Procedure

1. Connect to the TFE instance shell using your standard method.

2. Start a Rails console session. Run the following command as a user with Docker permissions, replacing tfe-atlas with ptfe_atlas if you are on an older version.

   $ docker exec -it tfe-atlas bash /usr/bin/init.sh /app/scripts/wait-for-token -- \
     bash -i -c 'cd /app && ./bin/rails c'

3. Verify the workspace's state. In the Rails console, find the workspace by name. This example uses aws-ws-dev-01.

   Workspace.find_by(name: 'aws-ws-dev-01')

4. Review the output and confirm the workspace is in a partially locked state. A key indicator is that locked_by_id has a value, but locked_reason is nil.

   irb(main):003:0> Workspace.find_by(name: 'aws-ws-dev-01')
   => #<Workspace id: 257, name: "aws-ws-dev-01", external_id: "ws-7HABBJu62a23234", organization_id: 2, created_at: "2020-10-30 10:31:58", updated_at: "2020-01-10 12:03:26", archived_at: nil, auto_apply: false, periodic_run: 0,queue_run_on_artifact_upload: false, terraform_version: "0.12.14", variable_set_id: nil, trace_resource_id: "c84251b4-8d0a-5167-9e4f-ae73bd961d2b",locked_by_id: 57, locked_by_type: "User", locked_reason: nil,environment: "default", current_state_version_id: [FILTERED], working_directory: "",ssh_key_id: nil, current_run_id: 4939, queue_all_runs: false,file_triggers_enabled: true, trigger_prefixes: [], speculative_enabled: true,source: "tfe-api", source_name: nil, source_url: nil, description: nil,allow_destroy_plan: true, auto_destroy_at: nil, agent_pool_id: nil,execution_mode: "remote", readme_id: nil, structured_run_output_enabled: nil,global_remote_state: [FILTERED], apply_duration_average: nil,plan_duration_average: nil, policy_check_failures: nil, run_failures: nil,workspace_kpis_runs_count: nil, remote_state_access: nil, runs_not_plan_only_count: 21,tag_list: nil>

5. Assign the workspace to a variable and unlock it.

   ws = Workspace.find_by(name: 'aws-ws-dev-01')
   ws.unlock(nil)

6. Log in to the TFE UI and confirm that you can now access the workspace.