How to fix resource is tainted, so must be replaced in Terraform

TerraformINTERMEDIATEHIGHUpdated Dec 30, 2025· 547 views

This error occurs when Terraform detects that a resource is in a degraded or incomplete state and must be destroyed and recreated. Learn how to handle tainted resources and fix this issue.

Quick fix

Fixes resource is tainted, so must be replaced

terraform plan
  1. Review the resource status and error logs
  2. Replace the resource using terraform apply
  3. Alternatively, use the replace flag for more control
  4. If the resource is actually healthy, untaint it
terraform — error
terraform plan
resource is tainted, so must be replaced

What this error means

When Terraform marks a resource as tainted, it means the resource exists in your infrastructure but may not be fully functional or has become corrupted. Terraform automatically marks resources as tainted when it detects incomplete creation (such as failed provisioner commands) or infers that an object is in a degraded state. During the next terraform apply, Terraform will destroy and recreate the tainted resource to restore it to a known-good state.

Typical symptoms

  • Your terraform apply plan shows "must be replaced (tainted)"
  • A resource fails to create properly but is partially deployed
  • External changes to the resource make Terraform think it's degraded
  • A provisioner command fails during resource creation

Common causes

  1. A provisioner (remote-exec, local-exec) failed during resource creation
  2. Terraform was interrupted during resource creation
  3. The resource provider detected an incomplete or degraded resource state
  4. Manual changes to the resource outside of Terraform
  5. Network or API errors during initial resource provisioning

How to fix "resource is tainted, so must be replaced"

1Review the resource status and error logs

Run terraform plan to see which resource is tainted and review the logs to understand why. Look for provisioner failures or API errors.

bash
terraform plan
2Replace the resource using terraform apply

Allow Terraform to replace the tainted resource by running apply. This will destroy and recreate it.

bash
terraform apply
3Alternatively, use the replace flag for more control

For Terraform 0.15.2+, use the -replace flag to replace a specific resource without affecting others. Preview the changes first with plan:

bash
terraform plan -replace="aws_instance.example"
terraform apply -replace="aws_instance.example"
4If the resource is actually healthy, untaint it

If you believe Terraform incorrectly marked the resource as tainted, remove the taint mark:

bash
terraform untaint aws_instance.example

Note: The taint command is deprecated since Terraform 0.15.2. Use -replace flag instead.

5Fix the underlying issue before retrying

If provisioners are failing, review and fix the provisioner scripts. Ensure:

- Provisioner commands are idempotent and error-free
- Network connectivity is available when provisioners run
- Required software/tools are installed on the target resource
- Scripts handle edge cases and failures gracefully

Advanced notes

If a resource continues to fail creation repeatedly, consider using lifecycle rules to handle failures gracefully. The lifecycle { create_before_destroy = true } option can help prevent state inconsistencies. For module resources, reference them with the full path: terraform replace 'module.my_module.aws_instance.example'. If you need to manually fix state issues, use terraform state rm to remove a resource entirely and terraform import to re-import it from your infrastructure.

Frequently asked questions

What does "resource is tainted, so must be replaced" mean?
When Terraform marks a resource as tainted, it means the resource exists in your infrastructure but may not be fully functional or has become corrupted. Terraform automatically marks resources as tainted when it detects incomplete creation (such as failed provisioner commands) or infers that an object is in a degraded state. During the next terraform apply, Terraform will destroy and recreate the tainted resource to restore it to a known-good state.
How do I fix "resource is tainted, so must be replaced"?
This error occurs when Terraform detects that a resource is in a degraded or incomplete state and must be destroyed and recreated. Learn how to handle tainted resources and fix this issue.
What causes "resource is tainted, so must be replaced"?
A provisioner (remote-exec, local-exec) failed during resource creation Terraform was interrupted during resource creation The resource provider detected an incomplete or degraded resource state
Is the "resource is tainted, so must be replaced" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading