Terraform State Explained: Locking, Drift, Imports and Recovery

Terraform forgets which real servers, databases and passwords it created. Its next plan then offers to create everything again, or to replace things it remembers wrongly. Terraform state is the memory that prevents this.

Picture a common setup. A four-person team in Pune runs its online shop's cloud resources from one Terraform folder. Two laptops apply from it, and so does a CI pipeline, which is automation that runs on every merge. The setup is made up, but every command result below came from our own test runs.

Three things go wrong in setups like this. Without a lock, two applies start at the same moment and both write the state file. Someone fixes a server by hand, so the code and the real world quietly disagree. Then one day the state file is deleted or half-written, and the next plan wants to build the shop from scratch.

This guide explains what the state file holds, why it leaks secrets, how backends and locks protect it, and how to recover it. Every example ran on Terraform 1.16.6 or OpenTofu 1.13.2 with local files only, so you can repeat it on a laptop with no cloud account.

Six words carry the whole guide. Each one is tied to the shop's setup.

• Resource: one block in your code that describes one real object, such as a server, a storage bucket or a generated password.
• Provider: a plugin that talks to one system's API, the interface programs use to control it, such as a cloud platform or your own disk. The shop's code uses the random and local providers in our tests.
• Plan: Terraform compares your code with what it knows about the real objects and lists the changes it would make.
• Apply: Terraform makes those changes, then writes down the result.
• State: the written-down result, a record of every object Terraform manages and the ID that identifies it in the real system.
• Backend: the place the state is stored and, for most backends, locked while a run writes it.

Terraform state is the record that links each resource in your code to one real object. The docs say Terraform uses it to map real-world resources to your configuration and to keep track of metadata.

Your code says what should exist, not which object already does. If the code says one server, Terraform needs to know whether that server is already running, and under which ID. The state answers that, so a second apply changes the existing server instead of creating a twin.

By default the state lives in a file named terraform.tfstate next to your code. Before planning, Terraform refreshes it: it asks each provider how every recorded object looks now. The docs also ask you never to edit this file by hand.

An everyday picture helps. A cloakroom gives you a token for your coat. The coats on the hooks are the real objects, your coat request is the code, and the token register is the state.

Without the register, every coat is still on its hook, but nobody can tell which one is yours. Lose the register and the attendant either hands out the wrong coat or takes in a second one.

Where the picture breaks: a real register holds a number, but Terraform's state also copies what is inside each coat. That includes anything secret in the pockets, which the next section shows.

Here is the shop's code reduced to three resources you can run anywhere. random_pet makes a server name, random_password makes a database password, and local_file writes both into a config file on disk.

terraform {
  required_providers {
    random = { source = "hashicorp/random", version = "3.9.1" }
    local  = { source = "hashicorp/local", version = "2.9.1" }
  }
}

resource "random_pet" "web" {
  length = 2
}

resource "random_password" "db" {
  length  = 16
  special = false
}

resource "local_file" "app_config" {
  filename = "${path.module}/app.env"
  content  = "SERVER=${random_pet.web.id}\nDB_PASSWORD=${random_password.db.result}\n"
}

output "db_password" {
  value     = random_password.db.result
  sensitive = true
}

Run terraform init, then terraform apply. You should see Apply complete! Resources: 3 added, 0 changed, 0 destroyed, and the output line db_password = (sensitive value) during the plan.

It is a JSON document with a few header fields and one entry per resource. Each entry stores the provider, the address in your code and every attribute the provider returned.

This is a trimmed copy from our run of the code above. We dropped most attributes and replaced the real password with a fake one. Every value shown is as Terraform wrote it.

{
  "version": 4,
  "terraform_version": "1.16.6",
  "serial": 4,
  "lineage": "e9068e21-ac6e-a407-6687-0a8dbd6c47af",
  "outputs": {
    "db_password": { "value": "FAKEpassw0rd1234", "type": "string", "sensitive": true }
  },
  "resources": [
    {
      "mode": "managed", "type": "random_password", "name": "db",
      "provider": "provider[\"registry.terraform.io/hashicorp/random\"]",
      "instances": [
        {
          "attributes": { "id": "none", "length": 16, "result": "FAKEpassw0rd1234" },
          "sensitive_attributes": [[{"type": "get_attr", "value": "bcrypt_hash"}], [{"type": "get_attr", "value": "result"}]]
        }
      ]
    }
  ]
}

Notice that the serial was already 4 after one first apply of three resources. In a separate test, adding three resources raised it by 4, while an apply with no changes left it alone. Treat serial as a count of state writes, not of applies.

You can read the same data without opening the file. terraform state list prints every tracked address, and terraform state show random_password.db prints one entry with secrets masked.

Because Terraform stores every attribute it needs to compare next time, and a password is an attribute. The docs say values marked sensitive are stored in both state and plan files.

The sensitive flag only changes what the screen shows. In our run, the plan showed db_password = (sensitive value) and terraform output masked it too. Yet the same password appeared three times in terraform.tfstate. It sat in the output, in random_password.db and inside the local_file content.

Anyone who can read the file can also read the value. terraform output -raw db_password printed the 16-character password in our run, and so did terraform show -json.

Plan files carry the same risk. A saved plan from terraform plan -out holds secrets too, so a CI pipeline that uploads plans as build artefacts is storing secrets there as well.

How do you keep secrets out of state or protect them?

• Keep state out of Git. The docs tell you to exclude it from Git workflows, because it is plain text.
• Use a backend that encrypts at rest and restricts who can read it. The S3 backend (S3 is Amazon's object storage service) has an encrypt option, and the docs say HCP Terraform, HashiCorp's hosted service, encrypts state at rest.
• Prefer values that never reach state. Terraform 1.10 added ephemeral values and resources, which exist only during a run and are never saved. Terraform 1.11 added write-only arguments, which a provider accepts but never stores in state; their names usually end in _wo.
• Watch data sources too. A data source reads existing data, and its result is saved in state. Our local_sensitive_file data source put a fake token straight into the state file.

We tested the ephemeral route with an ephemeral random_password block. The state file never mentioned it. When we passed it into a normal resource argument, Terraform 1.16.6 stopped with Error: Invalid use of ephemeral value.

Ephemeral values can only flow into places that are not saved, such as a provider's write-only arguments. Which resources offer write-only arguments depends on each provider, so check its docs.

How does OpenTofu encrypt state?

OpenTofu can encrypt the whole state file with a key you control. Its docs call AES-GCM, a standard authenticated cipher, the only currently supported encryption method. They also list an external-program method and an unencrypted mode used for migration. Keys can come from a passphrase, a cloud key service, OpenBao (an open-source secrets store) or an external program.

State encryption arrived in OpenTofu 1.7. Here is the setup we ran on OpenTofu 1.13.2, with a passphrase passed in as a variable.

terraform {
  required_providers {
    random = { source = "hashicorp/random", version = "3.9.1" }
  }

  encryption {
    key_provider "pbkdf2" "team_key" {
      passphrase = var.state_passphrase
    }

    method "aes_gcm" "main" {
      keys = key_provider.pbkdf2.team_key
    }

    state {
      method = method.aes_gcm.main
    }
  }
}

variable "state_passphrase" {
  type      = string
  sensitive = true
}

resource "random_password" "db" {
  length  = 16
  special = false
}

After apply, the state file held only encrypted_data, encryption_version, lineage, meta and serial. The word result did not appear in it at all. A wrong passphrase failed with a decryption error, and Terraform 1.16.6 rejected the encryption block as unsupported.

The SevyDevy guide on secrets management covers where those secrets should live instead. Here the lesson is narrower: whoever can read the state can read the secrets inside it.

A backend decides where Terraform stores state. Terraform uses the local backend by default, which is just the terraform.tfstate file in your folder.

Local state breaks as soon as two people share a project. The docs list the problems: each person must have the latest copy, and nobody else may run Terraform at the same time. A remote backend keeps one shared copy for the whole team.

Built-in backends include s3 for Amazon S3, an object storage service, and gcs, azurerm, pg, kubernetes and others. HCP Terraform uses a cloud block instead, and a configuration with a cloud block cannot also have a backend block.

One rule surprises people: a backend block cannot refer to variables, locals or data sources. Leave those arguments out and pass them at init time, which the docs call partial configuration. In our run, terraform init -backend-config="path=state/shop.tfstate" did this for a local backend. Keep credentials out of it: the docs say these values are saved in the .terraform folder and in plan files.

S3 native locking arrived in Terraform 1.10.0 in November 2024. The S3 backend page now says state locking is an opt-in feature of that backend, so an old setup with no lock settings has no lock.

For the shop, a sensible setup is one S3 bucket with versioning and encryption on and use_lockfile set to true. Read access goes only to the identity the CI pipeline runs as and a few engineers. We could not run S3 from our test machine, so this part rests on the docs alone.

Before any operation that could write state, Terraform takes a lock on it. If another run already holds the lock, Terraform stops instead of writing. The docs say it does not continue when locking fails.

On the local backend, the lock is an operating-system file lock on terraform.tfstate. In the Terraform 1.16.6 source it is an fcntl lock, the standard Unix file-locking call, on non-Windows systems. It is held only while the process runs.

We tested it by starting a slow apply and running a plan four seconds later. The plan failed at once with Error acquiring the state lock, Error message: resource temporarily unavailable. Below that it printed the lock's ID, path, operation, user, Terraform version and creation time.

While the apply ran, a small .terraform.tfstate.lock.info file held those details. It disappeared when the apply finished. Adding -lock-timeout=30s made the second plan wait about 15 seconds instead, then run normally.

What should you do when you see Error acquiring the state lock?

1. 1

   Read the lock info

   Note the Who, Operation and Created lines. They tell you which person or pipeline holds the lock and since when. If a parse or decryption error appears instead of Lock Info, the state file itself is broken; go to the recovery section.

2. 2

   Check that run is really dead

   Ask the person or look at the CI job. A lock held by a live apply is doing its job, so wait or retry with -lock-timeout.

3. 3

   Unlock only your own stale lock

   If your run crashed and left the lock, run terraform force-unlock with the lock ID. The docs warn that unlocking someone else's live run can cause two writers.

4. 4

   Never reach for -lock=false

   The docs call it dangerous when others might run against the same workspace. It skips the lock instead of fixing it.

force-unlock behaves differently on local state. Our attempt from a second process failed with Failed to unlock state: LocalState not locked. The docs agree that local state files cannot be unlocked by another process.

You rarely need it locally. We killed an apply with kill -9, a force-kill that gives the process no chance to clean up. Its .terraform.tfstate.lock.info file stayed behind, yet the next plan ran at once. The operating system had released the lock with the process, so a leftover info file proves nothing.

That killed apply left a different problem. The resource it was creating never reached state, so the next plan proposed creating it again. With a real cloud object, check whether it already exists before you apply.

Do not confuse the state lock with .terraform.lock.hcl. That file is the dependency lock file: it records the provider versions and checksums terraform init chose, and the docs say to commit it. It never locks state.

Drift is any difference between what the state says and what really exists, caused by a change made outside Terraform. A refresh-only plan shows that difference without proposing any change to real objects.

In the shop, picture someone deleting a config file on the server during a late-night fix. We copied that by deleting a file managed by a local_file resource named motd, then ran terraform plan -refresh-only.

It printed Note: Objects have changed outside of Terraform, then local_file.motd has been deleted, with every old attribute. It ended by saying it would not undo these changes, only record them if applied.

Pause and predict: what does a normal terraform plan say about the same deletion? Make a guess before reading on.

It said only local_file.motd will be created, Plan: 1 to add. There was no note that anything had changed outside Terraform. A normal plan quietly folds drift into its proposal.

We then edited the file's content by hand instead. The local provider reports a changed file as gone, so a normal plan again said will be created and would have overwritten the hand edit. How drift shows up depends on each provider.

The old terraform refresh command is deprecated. The docs call it an alias for terraform apply -refresh-only -auto-approve and warn it is risky. With misconfigured credentials it can wipe every object from state without asking.

Terraform 1.17.0, released on 21 October 2026, adds a -minimal-refresh option that refreshes only resources with proposed changes. We have not tested it, so check its docs before relying on it.

They let you change what state tracks through your code, so the change shows up in a normal plan before anything happens. The older terraform import, state mv and state rm commands change state immediately, with no plan to review.

Import blocks adopt objects that already exist

An import block names a real object's ID and the address it should get in your state. Terraform reads the object during the plan and shows will be imported, then saves it on apply.

Suppose the shop's API key suffix was created by hand months ago. random_string lets you import by the value itself, so this sample works without a cloud account. The value here is fake.

import {
  to = random_string.api_key_suffix
  id = "FAKEsuffix12"
}

resource "random_string" "api_key_suffix" {
  length = 12
}

With the other three resources already applied, the plan said Plan: 1 to import, 0 to add, 0 to change, 0 to destroy. After apply, a second plan with the import block still present said No changes.

The import only matches when your resource block matches the real object. In one test our block said special = false, but the imported value had the default of true. The plan said Warning: this will destroy the imported resource and planned to replace it.

So read every import plan for must be replaced. To get a starting block, terraform plan -generate-config-out=generated.tf writes one for you; in 1.16.6 it printed Config generation is experimental.

Two limits matter. A provider must support import for that resource type; local_file failed with Resource Import Not Implemented. Terraform 1.16.0 added import blocks inside child modules, and 1.16.6 accepted one in our test. OpenTofu 1.13.2 rejected the same block: Import blocks are only allowed in the root module.

Moved blocks rename without destroying

A moved block tells Terraform that an object recorded at one address now lives at another. Terraform updates the state before planning, so nothing is destroyed.

moved {
  from = random_pet.web
  to   = random_pet.frontend
}

We renamed random_pet.web to random_pet.frontend. Without the moved block, the plan was 2 to add and 2 to destroy: the pet, plus the config file that uses its name. With it, the plan said random_pet.web has moved to random_pet.frontend and Plan: 0 to add, 0 to change, 0 to destroy. The pet kept its old ID.

The refactoring docs strongly recommend keeping old moved blocks in shared modules. Someone still on an old version needs them, and removing one is a breaking change.

Removed blocks forget objects on purpose

A removed block takes an object out of state. With lifecycle destroy = false, the real object stays where it is. This suits handing a resource to another team or tool.

removed {
  from = local_file.app_config

  lifecycle {
    destroy = false
  }
}

After deleting the local_file block and adding this removed block, the plan said local_file.app_config will no longer be managed by Terraform, but will not be destroyed. After apply, app.env was still on disk and gone from state.

Leave out the lifecycle block and the two tools disagree. Terraform 1.16.6 planned to destroy the object. OpenTofu 1.13.2 planned 1 to forget and printed Warning: Missing lifecycle from the removed block. Always write destroy explicitly.

You restore the newest good copy, then make it match reality with a refresh-only plan and import blocks. Where that copy comes from decides how much work is left.

What failure looks like

We cut a state file down to its first 300 bytes. The next plan failed with Error acquiring the state lock, followed by Unsupported state file format: The state file could not be parsed as JSON. A broken file can surface as a lock error.

We then deleted the state completely. The plan offered to create every resource again: Plan: 2 to add. With real cloud objects, that means duplicates or name clashes.

Why the .backup file is not the latest copy

Local state keeps terraform.tfstate.backup, the state as it was before the latest command that changed it. In our run, one second apply took the live file to serial 6 while the backup stayed at serial 3.

Restoring that backup made Terraform plan the second apply's change again, with must be replaced on the resource it had changed. The backup is one step behind, so the plan after restoring it needs careful reading. Local state mv and state rm also wrote their own timestamped backups, named like terraform.tfstate.1793189595.backup.

Why state push refuses an old copy

terraform state push uploads a state file to the backend, with two safety checks. In our run it refused the backup with cannot import state with serial 3 over newer state with serial 6.

It also refused a file with a different lineage, calling it unrelated state. The -force flag skips both checks, and the docs say that is not recommended. Use it only when you know the newer copy is the broken one.

The recovery drill we ran

We applied one resource and saved a copy of the state as Monday's version. On Tuesday we added a random_string and applied again. Then we deleted the state and restored Monday's copy, as you would restore an older bucket version.

The plan wanted to create the Tuesday resource, because Monday's state had never heard of it. We wrote an import block with its real ID. The plan changed to 1 to import, 0 to add, and after apply it said No changes.

1. 1

   Stop every run

   Pause CI pipelines and tell the team. Nobody should apply while you are repairing state.

2. 2

   Save what you have

   Run terraform state pull and save the output, even if it looks wrong. Copy any .backup files too.

3. 3

   Find the newest good copy

   With a versioned bucket, list the state object's versions and pick the newest that parses. Locally, check the .backup and timestamped backup files.

4. 4

   Restore it

   Copying the old version back as the current file worked with no check in our local test. Pushing it instead needs -force for a lower serial, so double-check first.

5. 5

   See what changed since

   Run terraform plan -refresh-only and read every line. It shows objects that changed or vanished after that copy.

6. 6

   Adopt the orphans

   Objects created after the copy are missing from state. Add import blocks with their real IDs, plan, and look for will be imported, not will be created.

7. 7

   Finish at No changes

   Apply, then plan again until it says No changes. Write down what failed so the next fix is faster.

A pushed copy does not keep its old number either. When we forced the serial-3 backup over the state, which an earlier test push had raised to serial 7, the result had serial 4, below what it replaced. Expect that, and keep your own copy before any push.

Mostly it does not. OpenTofu 1.13.2 read and planned against a state file that Terraform 1.16.6 had written in our test. Three differences showed up in our runs.

The bigger difference is the second row. A config written for OpenTofu that leans on the forget default would destroy real objects under Terraform. Writing destroy = false, or true, removes the doubt in both tools.

Interviewers ask about state when you propose infrastructure as code, which is managing servers and networks through reviewed code files. Show you know the risks, not only the commands.

1. 1

   Say what state is

   A record that maps each resource in code to a real object ID, refreshed before every plan.

2. 2

   Name the risk in the file

   It stores attributes in plain text, including secrets, so access to state means access to secrets.

3. 3

   Pick the backend

   A remote backend with locking, encryption and versioning, such as S3 with use_lockfile on. Limit who can read it.

4. 4

   Limit the blast radius

   Blast radius is how much one failure can damage. Keep separate state per environment or component, so one broken file cannot block everything.

5. 5

   Handle drift

   Run a nightly plan with -detailed-exitcode and treat exit code 2 as an alert. Review with -refresh-only.

6. 6

   Change state through code

   Use import, moved and removed blocks so every state change is planned and reviewed.

7. 7

   Plan the recovery

   Bucket versioning, a written drill, and import blocks to adopt objects created after the restored copy.