How to fix Error: replace_triggered_by argument is invalid in Terraform

TerraformINTERMEDIATEMEDIUMUpdated Dec 30, 2025· 214 views

The replace_triggered_by lifecycle argument is invalid because it references a variable, data source, or non-existent resource. This argument only accepts managed resource references and was introduced in Terraform 1.2.

Quick fix

Fixes Error: replace_triggered_by argument is invalid

terraform version
  1. Verify your Terraform version is 1.2 or later
  2. Review the resource you're trying to reference
  3. Use only managed resource references in replace_triggered_by
  4. Use terraform_data for variable-based replacements
terraform — error
terraform version
Error: replace_triggered_by argument is invalid

What this error means

The replace_triggered_by lifecycle meta-argument tells Terraform to replace a resource when another resource changes. It was introduced in Terraform 1.2. However, it has strict requirements about what can be referenced—only managed resources are allowed. When you try to reference local values, input variables, data sources, or non-existent resources, Terraform throws an "invalid" error because these constructs don't have the planned actions needed for replacement triggering.

Typical symptoms

  • Error message: 'replace_triggered_by argument is invalid'
  • Error during terraform plan or terraform validate
  • Message mentions 'Missing resource reference' or 'not a resource'
  • Configuration fails when using variables inside replace_triggered_by list

Common causes

  1. Attempting to reference a variable or local value in replace_triggered_by
  2. Referencing a data source in replace_triggered_by
  3. Using replace_triggered_by with Terraform version < 1.2
  4. Referencing a resource that doesn't exist or has been deleted
  5. Incorrect syntax in the resource reference (missing resource type or name)
  6. Attempting to reference self-properties or the containing instance

How to fix "Error: replace_triggered_by argument is invalid"

1Verify your Terraform version is 1.2 or later

The replace_triggered_by argument was introduced in Terraform 1.2. Check your version:

bash
terraform version

If you're using an older version, upgrade Terraform to at least 1.2:

bash
# Using tfenv (recommended)
tfenv install 1.2.0
tfenv use 1.2.0

# Or download from https://www.terraform.io/downloads
2Review the resource you're trying to reference

Ensure the referenced resource exists and is a managed resource (not a variable or data source). List all resources in your configuration:

bash
terraform state list

Verify the resource name matches exactly. Common mistakes:
- Typos in resource type or name
- Using aws_instance instead of just the resource reference
- Referencing a deleted or commented-out resource

3Use only managed resource references in replace_triggered_by

Only managed resources can be referenced. This is INVALID:

hcl
resource "aws_instance" "example" {
  lifecycle {
    # WRONG: referencing a variable
    replace_triggered_by = [var.ami_version]

    # WRONG: referencing a data source
    replace_triggered_by = [data.aws_ami.latest]

    # WRONG: referencing a local value
    replace_triggered_by = [local.instance_config]
  }
}

This is CORRECT:

hcl
resource "aws_instance" "example" {
  lifecycle {
    # RIGHT: referencing managed resources
    replace_triggered_by = [
      aws_security_group.default,
      aws_ami.ubuntu
    ]
  }
}
4Use terraform_data for variable-based replacements

If you need to trigger replacements based on variable changes, use the terraform_data resource as an intermediary:

hcl
resource "terraform_data" "ami_version" {
  input = var.ami_version
}

resource "aws_instance" "example" {
  ami = data.aws_ami.latest.id

  lifecycle {
    replace_triggered_by = [terraform_data.ami_version]
  }
}

This works because terraform_data is a managed resource that Terraform tracks for planned changes.

5Validate your configuration syntax

Check for syntax errors in your resource references:

bash
terraform validate

The output will highlight exactly which resource reference is invalid. Common syntax errors:
- Missing resource type: aws_sg instead of aws_security_group.example
- Including brackets: [aws_instance.example.id] instead of [aws_instance.example]
- Using string literals: ["aws_instance.example"] instead of [aws_instance.example]

6Check for circular dependencies

Ensure that adding replace_triggered_by doesn't create a dependency cycle. For example, if Resource A depends on Resource B, and you make Resource B's replacement depend on Resource A, Terraform cannot resolve the order:

hcl
# BAD: Creates a cycle
resource "aws_instance" "app" {
  security_groups = [aws_security_group.app.id]  # A depends on B

  lifecycle {
    replace_triggered_by = [aws_security_group.app]  # B depends on A
  }
}

Use terraform_data or restructure dependencies to break the cycle.

Advanced notes

Understanding lifecycle restrictions:

The replace_triggered_by argument only accepts managed resource references because Terraform needs to track planned changes to those resources. Variables and locals don't have "planned actions" in Terraform's execution model, so they can't trigger lifecycle actions directly.

Using terraform_data for flexibility:

The terraform_data resource is a meta-resource that allows you to create resource-like behavior for values that aren't infrastructure. This is the recommended pattern when you need variable-based replacement triggers.

Conditional creation with for_each/count:

When using replace_triggered_by with resources that use for_each or count, you can reference specific instances:

hcl
resource "aws_instance" "app" {
  for_each = var.instances

  lifecycle {
    replace_triggered_by = [
      aws_security_group.app[each.key]  # Reference matching instance
    ]
  }
}

Version compatibility:

- Terraform 1.2+: Full replace_triggered_by support
- Terraform < 1.2: Use triggers in null_resource with local-exec provisioner as workaround
- Terrascan and other static analyzers may not recognize replace_triggered_by if they use outdated Terraform parsing

Frequently asked questions

What does "Error: replace_triggered_by argument is invalid" mean?
The replace_triggered_by lifecycle meta-argument tells Terraform to replace a resource when another resource changes. 2. However, it has strict requirements about what can be referenced—only managed resources are allowed.
How do I fix "Error: replace_triggered_by argument is invalid"?
The replace_triggered_by lifecycle argument is invalid because it references a variable, data source, or non-existent resource. This argument only accepts managed resource references and was introduced in Terraform 1.2.
What causes "Error: replace_triggered_by argument is invalid"?
Attempting to reference a variable or local value in replace_triggered_by Referencing a data source in replace_triggered_by Using replace_triggered_by with Terraform version < 1.2
Is the "Error: replace_triggered_by argument is invalid" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading