We earn commissions when you shop through the links below, at no extra cost to you. Our guides and technical recommendations are written independently of these relationships: a commission never decides what we recommend, how we diagnose a problem or what we publish, and the content does not depend on it. Affiliate disclosure

Terraform · Intermediate · 12 min

Fix Terraform 'Error acquiring the state lock'

Fix Terraform "Error acquiring the state lock": read the lock, find the run that holds it, wait or force-unlock a stale lock, and check the state.

A state lock stops two runs from writing the same state. This runbook reads the lock info, checks whether its holder is still running, removes a stale lock with force-unlock, and checks the state after a run that was killed. Commands were run with Terraform 1.17.0 against local state and an S3-compatible backend in a local container.

See it run

A short replay of real output from commands in this guide, captured on a WSL2 Ubuntu test machine (Terraform 1.17.0, S3 backend with use_lockfile against SeaweedFS 4.50 in a local container, built-in terraform_data resource only). The typing is replayed, and the host name, account and MAC addresses are redacted. Your output will differ, and a test machine is not a production server.

Text version of this demo
ops@web-01:~$ terraform plan -input=false

Error: Error acquiring the state lock

Error message: operation error S3: PutObject, https response error
StatusCode: 412, RequestID: 18E3AE8DDE84B8F832D5BC97, HostID: , api error
PreconditionFailed: At least one of the pre-conditions you specified did not
hold
Lock Info:
  ID:        b9e022b1-ec54-5974-6344-bc99ba9b8154
  Path:      tfstate/app/terraform.tfstate
  Operation: OperationTypeApply
  Who:       ops@web-01
  Version:   1.17.0
  Created:   2026-10-31 17:49:46.769739866 +0000 UTC
  Info:      


Terraform acquires a state lock to protect the state from being written
by multiple users at the same time. Please resolve the issue above and try
again. For most commands, you can disable locking with the "-lock=false"
flag, but this is not recommended.

ops@web-01:~$ pgrep -af terraform || echo "no terraform process is running"
no terraform process is running

ops@web-01:~$ curl -s http://localhost:8333/tfstate/app/terraform.tfstate.tflock | jq .
{
  "ID": "b9e022b1-ec54-5974-6344-bc99ba9b8154",
  "Operation": "OperationTypeApply",
  "Info": "",
  "Who": "ops@web-01",
  "Version": "1.17.0",
  "Created": "2026-10-31T17:49:46.769739866Z",
  "Path": "tfstate/app/terraform.tfstate"
}

ops@web-01:~$ terraform force-unlock -force "$(curl -s http://localhost:8333/tfstate/app/terraform.tfstate.tflock | jq -r .ID)"
Terraform state has been successfully unlocked!

The state has been unlocked, and Terraform commands should now be able to
obtain a new lock on the remote state.

ops@web-01:~$ terraform plan -input=false | grep -E '^Plan:|No changes'
Plan: 1 to add, 0 to change, 0 to destroy.

Terraform locks the state before any operation that could write it, so two runs cannot change the same state at once. Error acquiring the state lock means another run holds that lock. Usually it is a real run that is still working, and the right fix is to wait. Sometimes the run died (a killed CI job, a closed laptop) and left the lock behind. This runbook tells the two apart, removes a stale lock safely, and checks the state after a run that was cut off.

Commands and output were captured with Terraform 1.17.0 on Ubuntu 26.04, with the built-in terraform_data resource and two backends: local state, and the S3 backend with native lock files (use_lockfile = true) against SeaweedFS 4.50, an S3-compatible store in a local container. Nothing was created in any cloud.

0. Rules of engagement

  1. Assume the lock is real until you have proved otherwise. Removing the lock of a run that is still applying lets two runs write the same state, and that can corrupt it or lose resources.
  2. Never use -lock=false on shared state to get past this error.
  3. Find the holder first: the lock tells you who and when.

1. Read the lock

# Real output from the test setup: a second apply while the first one is still running (S3 backend)
Error: Error acquiring the state lock

Error message: operation error S3: PutObject, https response error
StatusCode: 412, RequestID: 18E3AE45D682169CB26F308F, HostID: , api error
PreconditionFailed: At least one of the pre-conditions you specified did not
hold
Lock Info:
  ID:        791a3110-f943-840c-55d0-47aa2f04fa3f
  Path:      tfstate/app/terraform.tfstate
  Operation: OperationTypeApply
  Who:       ops@web-01
  Version:   1.17.0
  Created:   2026-10-31 17:44:45.600357185 +0000 UTC
  Info:
FieldWhat it tells you
IDThe lock ID. force-unlock needs exactly this value
PathWhich state is locked: bucket and key, or a local file
OperationWhat the holder was doing: OperationTypeApply, OperationTypePlan, OperationTypeInvalid (other commands, such as state rm or import)
WhoUser and host of the holder. In CI this is the runner's user and machine name
CreatedWhen the lock was taken, in UTC. A few minutes ago: probably still running. Hours ago: probably stale

The Error message line depends on the backend. The S3 lock file gives 412 PreconditionFailed, because a lock file already exists. The local backend gives resource temporarily unavailable. The older S3 setup with a DynamoDB table gives ConditionalCheckFailedException.

2. Is the holder still running?

  • On your machine: pgrep -af terraform lists Terraform processes.
  • In CI: look for a running or queued job for the same state (same repository, workspace or environment) that started near the Created time.
  • Another person: Who usually names them. Ask.

If it is still running, wait for it. Or let your command wait for the lock instead of failing at once:

# Wait up to five minutes for the lock instead of failing immediately
terraform plan -lock-timeout=5m

On the test setup, a plan started six seconds into a 25-second apply waited, then went on: real 0m31.081s, with no error.

3. A stale lock: the run died and left it

When a run is killed with SIGKILL, it cannot release its lock. A crashed machine or a CI job killed after its grace period does the same. On the S3 backend the lock file then stays in the bucket next to the state, and every later run fails with the same error and the same lock ID.

# Real output from the test setup: the bucket after the first apply was killed with kill -9
<Key>app/terraform.tfstate.tflock</Key>

Where the lock lives:

BackendThe lock
S3 with use_lockfile = true (current Terraform versions)An object KEY.tflock next to the state object
S3 with dynamodb_table (deprecated)An item in the DynamoDB table
Google Cloud StorageA lock object next to the state in the bucket
Azure (azurerm)A lease on the state blob
HCP Terraform, Terraform EnterpriseThe workspace lock, shown and released in the UI
localAn operating system lock on terraform.tfstate, plus the file .terraform.tfstate.lock.info

The local backend is the exception. The operating system releases its lock when the process dies. On the test machine, after kill -9, the .terraform.tfstate.lock.info file was still there, but the next terraform plan worked. A local lock error therefore means a Terraform process really is running. force-unlock cannot remove that lock from another process. It refused with Failed to unlock state: LocalState not locked.

4. Remove a stale lock with force-unlock

Only when you are sure that no run holds the lock (section 2):

# Release the lock with the exact ID from the error message
terraform force-unlock LOCK_ID
# Real output from the test setup
Terraform state has been successfully unlocked!

The state has been unlocked, and Terraform commands should now be able to
obtain a new lock on the remote state.
  • Run it in the same folder and workspace as the failing command, so it uses the same backend configuration.
  • Without -force, it asks for confirmation. Keep that in interactive use.
  • Do not delete the lock file or DynamoDB item by hand unless force-unlock cannot reach the backend. If you must, record what you deleted and why.

5. Check the state after a run that was cut off

A killed apply may have created or changed real resources and never written them into the state. On the test setup, the killed apply had already run its provisioner, but after the unlock, the plan wanted to create the resource again: Plan: 1 to add, 0 to change, 0 to destroy.

  • Read the plan carefully before the next apply. Resources it wants to create may already exist, which leads to duplicates or "already exists" errors.
  • Import what exists (an import block or terraform import) instead of creating it twice.
  • If the state upload failed, Terraform writes errored.tfstate in the working folder. Do not delete it. terraform state push errored.tfstate uploads it once the backend works again.
  • With bucket versioning (recommended for state buckets), an earlier state version can be restored if the newest one is wrong.

6. Verify

# The next plan takes the lock, finishes, and releases it
terraform plan

It shows a plan or No changes, not the lock error. Run it twice: the second run proves the first released the lock.

7. Rollback and prevention

  • Rollback: force-unlock cannot be undone. If it turns out the holder was still running, stop all runs for that state, compare the state with the real infrastructure, and restore an earlier state version if needed.
  • One run per state in CI: use a concurrency group (for example concurrency: in GitHub Actions, or resource_group in GitLab) for every job that plans or applies the same state.
  • Give CI jobs a graceful stop: on SIGINT or SIGTERM, Terraform stops and releases the lock. Set the job's cancel grace period long enough for that, and avoid killing runners hard.
  • Use -lock-timeout in CI, so a short overlap waits instead of failing.
  • Enable versioning on the state bucket, so a bad write can be rolled back.

References

Official reference

developer.hashicorp.com ↗

Technical steps are original explanations; consult the upstream documentation for version-specific details.

Behavior differs by distribution and tool version. Commands are examples for authorized systems; review output for secrets before sharing.

Found this useful?

Follow us on YouTube for video explainers, and find us on Facebook to keep up with what is new.