Completely remove state in TF Cloud


In my testing, things have got in a mess and I want to completely delete the remote state file, managed by TF Cloud and start again. I’ve already deleted the (Azure) resource group.

When I configured remote state to live in an Azure storage account, this was as simple as deleting the state file (blob), but no amount of Googling is giving me the answer.

I’ve had a brief look at the TF Cloud API, but cannot see a delete operation.

Any pointers will be gratefully received.

Many thanks in advance.


Hi @woter324,

Terraform Cloud’s state storage API is at a higher level of abstraction than the generic “blob storage” systems targeted by most other backends, and so it enforces some additional constraints to try to ensure that it isn’t possible to upload something that would be totally invalid to Terraform, and that it’s hard to accidentally clobber a valid state snapshot with something invalid or incomplete.

However, unfortunately that does mean that there isn’t really a direct “delete” operation, because conceptually a Terraform Cloud Workspaces always has a “current state”, it’s just initially empty.

With that in mind, one way to create the effect of “deleting” the state might be to push an entirely-empty state snapshot, overwriting your most recent state snapshot containing references to remote objects.

I’m not aware of any ready-to-use mechanism for that, since intentionally discarding everything is a rare and dangerous operation, but I think something like the following process would work:

  1. In a working directory already initialized to use your remote Terraform Cloud workspace using terraform init, run terraform state pull and redirect its output to a file to obtain a local copy of the latest state snapshot in the usual JSON-based internal format.

  2. Open that file in your favorite text editor and carefully delete all of the elements from the JSON array assigned to the "resources" property. This is essentially the same as running terraform state rm for each resource instance in turn, but performed all as a single step.

    You can also optionally empty the outputs JSON object if you want to remove any output values tracked there, but that isn’t strictly necessary because Terraform will rebuild that object itself at the next apply anyway.

  3. Find the "serial" property at the top-level and increment it by 1. This confirms to Terraform that you are intentionally trying to create a new state snapshot based on the previous one.

  4. Use terraform state push with the file you’ve just edited to submit that snapshot as the new latest snapshot for your workspace.

Your workspace should then have a latest state snapshot that doesn’t track any remote objects, which is the same way the other blob-storage-based state storage implementations would interpret a totally-missing state object.

If others are also using your workspace then there is some risk that someone will create a new state snapshot between step 1 and step 4, in which case step 4 will fail because the serial number would collide with an existing snapshot. In that case, repeat the whole process again based on the updated snapshot. Of course if you can ensure that no coworkers will be creating new snapshots while you are working then you can avoid this sort of conflict, but I mention it just in case.

Thank you @apparentlymart