terraform state mv: Usage & Common CI Errors

Rename or relocate a resource in state without destroying and recreating it.

terraform state mv updates the address of a resource in state. It is how you refactor - renaming a resource or moving it into a module - without Terraform proposing a destroy/create.

What it does

terraform state mv <source> <destination> rewrites the state so an existing object is tracked under a new address. Without it, renaming a resource in config makes Terraform plan a destroy of the old name and a create of the new one. Modern configs can use a moved {} block instead for the same effect, version-controlled.

Common usage

# Rename a resource
terraform state mv aws_instance.web aws_instance.app

# Move a resource into a module
terraform state mv aws_db_instance.this module.db.aws_db_instance.this

# Move a for_each instance
terraform state mv 'aws_iam_user.team["bob"]' 'aws_iam_user.admins["bob"]'

Common error in CI: destination already exists

state mv fails with "Error: Invalid target address ... already exists" when something already occupies the destination, or "Invalid source address" when the source address is wrong. Fix: confirm both addresses with terraform state list, ensure the destination is empty (state rm it first if it holds a stale object), and quote bracketed for_each/count addresses. Prefer a moved {} block in config so the refactor is reviewable and reproducible in CI.

Key options

Related guides