A Terraform plan can stop with Error acquiring the state lock even when no teammate appears to be running an apply. The message is stressful because state locking protects shared infrastructure state from concurrent writes. The dangerous shortcut is to disable locking or immediately run terraform force-unlock. If another process still owns the lock, removing it can allow two writers to modify the same state and leave the state inconsistent with real infrastructure.
This guide explains how to investigate a Terraform state lock safely, identify a stale lock, and recover without guessing. Examples assume you are in the correct Terraform working directory and have authenticated to the intended backend. Do not share lock metadata or state files publicly if they reveal internal resource names or sensitive values.
Symptoms: what the lock error tells you
Terraform locks state automatically for operations that could write it when the configured backend supports locking. If Terraform cannot acquire the lock, it stops rather than proceeding unsafely. The error may include a lock ID, operation, creation time, user, and path or workspace metadata. Preserve that output. It is evidence for determining whether a real operation is still active.
terraform workspace show
terraform version
terraform plan -lock-timeout=60sRun the plan only after confirming the workspace and backend are correct. A short -lock-timeout waits for a lock to become available; it does not remove the lock. If the same error persists, investigate the owner rather than repeatedly starting new applies.
Root causes: active operation or stale lock?
A lock can be legitimate: a teammate may be applying changes, a CI job may still be running, or a previous command may be waiting on a slow provider operation. It can also remain after a runner crash, interrupted terminal session, lost network connection, or backend failure during unlock. A lock record by itself does not tell you which case applies.
Check the team deployment system, CI job history, terminal sessions, and the backend’s audit or access logs. Confirm that no Terraform process is still active for this workspace. Also confirm that the lock belongs to this exact backend and state key; similar project names do not guarantee the same state.
Diagnosis: inspect the operation before touching the lock
Read the full lock error and identify the unique lock ID. Ask the named operator or CI owner whether the operation is still running. Check the runner’s status and logs, including whether it is waiting on a provider API. If the backend exposes lock metadata, inspect it using the backend’s supported administrative interface. Avoid editing the backend’s lock record directly.
Check that the local directory and workspace are what you expect:
pwd
terraform workspace show
terraform state listterraform state list reads state and does not intentionally modify infrastructure, but it still requires valid backend access and may be subject to backend behavior. Do not use terraform state pull casually in shared logs: state can contain secrets and sensitive attributes. If a backup is required, store it in a restricted location and follow your organization’s retention policy.
Fix: wait, recover the owner, or force-unlock only your stale lock
If a CI apply or teammate’s operation is active, wait for it to finish. Do not run a second apply. If the runner is stuck but still executing provider calls, coordinate with the operator before terminating it. The correct recovery may be to let the operation complete or to follow the provider-specific interruption procedure.
If you have established that the operation terminated unexpectedly, automatic unlocking failed, and the lock is yours, use the exact lock ID printed by Terraform:
terraform force-unlock LOCK_IDTerraform prompts for confirmation. Do not add -force merely to skip the prompt. The lock ID acts as a safeguard so the unlock targets the intended lock. Force-unlock removes the state lock; it does not modify infrastructure. It is not a general-purpose way to clear a lock created by another operator.
Never use -lock=false as a routine workaround. Disabling locking removes the protection against concurrent state writers. It can turn a temporary availability problem into a state consistency problem that is much harder to repair.
Validation: prove the workspace is safe to use again
After a confirmed stale lock has been removed, verify that the backend is accessible and the expected workspace remains selected:
terraform workspace show
terraform plan -lock-timeout=60sReview the plan carefully. If it proposes unexpected resource replacement, deletion, or recreation, stop and investigate before applying. Compare the state with the actual infrastructure using the normal review process. A successful plan does not mean every remote resource is healthy; it means Terraform can now read state and calculate a proposed change.
For a production change, require the normal peer review and approval before terraform apply. Ensure the CI pipeline serializes applies for the same state key and that developers use the same backend and workspace conventions.
Rollback and state recovery
Unlocking is not an infrastructure rollback. If a prior interrupted apply partially changed real resources, reconcile the state and infrastructure carefully. Do not restore an old state file simply because the lock error occurred: the remote infrastructure may already have changed. A stale state snapshot can cause Terraform to propose destructive actions.
If state recovery is genuinely required, first preserve the current state securely, identify the correct backup, compare lineage and serial information, and follow HashiCorp’s recovery procedure. Avoid direct JSON edits and avoid terraform state push unless you understand the consequences and have an approved recovery plan. State can contain credentials and other sensitive values, so protect every copy.
Prevent repeat incidents
Use one remote backend and a consistent state key per environment. Serialize CI applies for the same workspace, cancel obsolete jobs safely, and make deployment ownership visible. Keep Terraform versions and provider constraints consistent across local and CI environments. Configure an appropriate lock wait for normal contention, but do not confuse waiting with unlocking. Document who may force-unlock and require evidence that the original operation has ended.
Operator checklist
- Confirm the backend, directory, and workspace.
- Capture the lock ID and full error details.
- Check active CI jobs, teammate operations, and backend activity.
- Do not disable locking or edit backend lock records manually.
- Force-unlock only a confirmed stale lock from your own failed operation.
- Run a fresh plan and review unexpected changes before applying.
- Protect state backups because they may contain secrets.
Primary references
HashiCorp: State Locking; HashiCorp: terraform force-unlock; HashiCorp: Recover State from Backup; HashiCorp: State Backends and Locking. Related ProdCraft guide: Terraform infrastructure-as-code workflow.
