Terraform state rm: Remove Resources from State (2026)

Terraform’s state rm command is surprisingly complex, often leading to more questions than it answers about how your infrastructure is actually managed.

Let’s say you’ve accidentally provisioned a resource, like an AWS S3 bucket, and you want Terraform to stop managing it. You don’t want to delete the actual bucket in AWS, just tell Terraform to forget about it. This is where terraform state rm comes in.

Here’s a real-world scenario:

resource "aws_s3_bucket" "my_bucket" {
  bucket = "my-unique-terraform-managed-bucket-12345"
  acl    = "private"

  tags = {
    Environment = "Dev"
    ManagedBy   = "Terraform"
  }
}

You run terraform apply, and that bucket is created. Now, for whatever reason, you decide this bucket should no longer be managed by Terraform. Maybe it’s a legacy resource, or you’re moving it to a different management system.

You might think terraform state rm aws_s3_bucket.my_bucket is all you need. And often, it is.

But what if you run that and get an error like: Error: Resource not found for given address? Or worse, it seems to work, but your next terraform plan shows the bucket being destroyed and recreated?

The core issue is that terraform state rm doesn’t interact with your cloud provider at all. It only modifies your Terraform state file. The state file is Terraform’s single source of truth about what infrastructure it’s currently managing. Think of it as a detailed map of your deployed resources and how they relate to your Terraform configuration.

When you run terraform state rm <resource_address>, you’re telling Terraform: "Hey, this resource at <resource_address> is no longer under my control. Please remove it from your map (the state file)."

Here’s how that looks in action. First, let’s create that S3 bucket and then remove it from state.

# Initialize Terraform
terraform init

# Apply the configuration to create the bucket
terraform apply -auto-approve

# Verify the bucket exists in AWS (e.g., via AWS CLI or console)
aws s3 ls | grep my-unique-terraform-managed-bucket-12345

# Now, remove the resource from Terraform state
terraform state rm aws_s3_bucket.my_bucket

After running terraform state rm aws_s3_bucket.my_bucket, if you inspect your terraform.tfstate file (or your remote state backend), you’ll see the aws_s3_bucket.my_bucket entry is gone. If you then run terraform plan, Terraform will see that aws_s3_bucket.my_bucket is no longer in its state and assume it needs to be created. This is the common pitfall: state rm alone doesn’t prevent a future apply from trying to provision it again if it’s still defined in your .tf files.

The most common reason terraform state rm fails with "Resource not found" is simple: the resource address you provided doesn’t match anything currently in your state file. This can happen if:

• You mistyped the resource address: Double-check aws_s3_bucket.my_bucket against your .tf files and the state. It’s case-sensitive and requires the exact module path if it’s in a module.
• The resource was already removed: Perhaps you or someone else already ran terraform state rm for this resource.
• The resource was never managed by Terraform: You might be trying to remove something that was created manually or by another tool.

To diagnose this, you can list your current state:

terraform state list

This command will output a list of all resources currently tracked by Terraform. Find the exact address from this list to use with state rm.

If terraform state rm succeeds, but terraform plan still shows the resource being created, it means you still have the resource defined in your Terraform configuration (.tf files). state rm only removes it from the state file; it doesn’t touch your configuration.

The fix: Comment out or remove the resource block from your .tf files after running terraform state rm.

# resource "aws_s3_bucket" "my_bucket" {
#   bucket = "my-unique-terraform-managed-bucket-12345"
#   acl    = "private"
#
#   tags = {
#     Environment = "Dev"
#     ManagedBy   = "Terraform"
#   }
# }

After commenting out the resource block and running terraform plan again, Terraform will see that the resource is no longer defined in your configuration and is no longer in the state file, so it won’t try to create it.

Another common scenario is when you’ve deleted the actual resource in your cloud provider (e.g., manually deleted the S3 bucket via the AWS console) but Terraform still thinks it exists in its state file. If you then run terraform plan, Terraform will try to "update" the non-existent resource. Running terraform state rm in this case will likely give you the "Resource not found" error because the resource’s ID (e.g., the bucket name or ARN) is no longer valid.

The solution here is to first refresh your state to reflect the actual infrastructure, which will mark the missing resource as tainted or removed, and then manage its removal from the state.

# First, refresh the state to detect the missing resource
terraform refresh

# If the resource is now marked as 'not found' or 'tainted' in the plan,
# you can then try to remove it from state.
# However, 'terraform refresh' might have already removed it from state
# if it was a complete deletion. If not, you'd proceed with:
terraform state rm <resource_address>

# Then, comment out the resource in your .tf files.

A more advanced, but sometimes necessary, technique involves directly editing the state file. This is generally discouraged unless you know exactly what you’re doing, as a corrupted state file can be disastrous. You’d typically use terraform state mv to move resources or terraform state pull and terraform state push to manually edit and re-upload the state file.

Consider a situation where a resource was created with a dynamic name, like an S3 bucket whose name includes a random string or a count index. If you want to remove aws_s3_bucket.example[0], you need to ensure aws_s3_bucket.example[0] is precisely what’s in your state.

The command terraform state rm -dry-run <resource_address> is your friend here. It shows you what would be removed without actually doing it, helping you verify the address.

If you’re using provisioners (like remote-exec or local-exec), and those provisioners fail, they can sometimes leave the resource in an inconsistent state, making state rm behave unexpectedly. In such cases, you might need to manually remove the resource from the state file after ensuring the actual resource is gone or no longer needed.

Finally, if you’re working with remote state backends (like S3, Azure Blob Storage, GCS), terraform state rm still operates locally first and then pushes the changes to the remote backend. Network issues or permission problems during this push can cause the operation to appear successful locally but fail remotely, leaving your state inconsistent. Always check your remote state backend after performing state manipulation.

The next hurdle you’ll likely encounter after successfully removing resources from state is dealing with resources that have dependencies on the ones you just removed. Terraform’s dependency graph will complain, and you’ll need to carefully re-evaluate your configuration and potentially adjust those dependencies.