Force Unlock

When to Force Unlock

Terraform locks state during plan/apply to prevent concurrent modifications. If a run is interrupted (timeout, crash, network failure), the lock may persist and block future runs.

Force unlock when:

• A run timed out or failed mid-apply
• The state is locked and no run is in progress
• You’ve confirmed no other process is modifying the state

Warning: Force unlocking while another process is actively writing state can cause corruption. Only force unlock when you’re certain no other process holds the lock.

Triggering a Force Unlock

POST /workspaces/{id}/force-unlock
{ "lock_id": "optional-lock-id" }

The lock_id is optional. If provided, it’s passed to the unlock command.

What Happens

1. Forgecroft checks for concurrent force-unlock runs (409 if one is already queued or in progress)
2. Finds the most recent timed out or failed run for audit context
3. Creates a standalone unlock run (not linked to any changeset)
4. The unlock run releases the state lock
5. Any other in_progress run for the workspace is forced to timed_out

Response

{
  "unlock_run_id": "uuid",
  "timed_out_run_id": "uuid"
}

• unlock_run_id — The ID of the unlock run that was created
• timed_out_run_id — The ID of the run that was forced to timed_out (if any)

Unlock Run Status

The unlock run has run_type: "unlock" and action: "forceunlock". It reaches unlocked status on success.

Related API Endpoints

• POST /workspaces/{id}/force-unlock — Trigger a force unlock
• GET /workspaces/{workspaceId}/runs/{runId} — View unlock run status