terraform state rm: Usage & Common CI Errors

Tell Terraform to forget a resource - without deleting it.

terraform state rm removes a resource from state so Terraform stops managing it. The real infrastructure is untouched; only the binding is dropped.

What it does

terraform state rm <address> deletes the resource’s entry from state. The next plan will no longer try to update or destroy that object, and (if it is still in your config) Terraform will propose recreating/importing it. Use it to hand a resource off to another module or to a manual workflow.

Common usage

# Stop managing a resource (does NOT destroy it)
terraform state rm aws_instance.legacy

# Remove an entire module's resources from state
terraform state rm 'module.old_network'

# Remove a single for_each instance
terraform state rm 'aws_iam_user.team["alice"]'

Common error in CI: state lock held by another run

state rm fails with "Error: Error acquiring the state lock ... ConditionalCheckFailedException" when another plan/apply holds the lock. Fix: wait for the other run to finish, or if the lock is stale (a crashed job), confirm nothing is running and clear it with terraform force-unlock <LOCK_ID>. Never force-unlock while a real apply is in flight - it can corrupt state.

Key options

Related guides