How to fix Error: Invalid template interpolation value in Terraform

TerraformINTERMEDIATEMEDIUMUpdated Dec 30, 2025· 173 views

This error occurs when you try to include a non-string value (like a list or tuple) directly in a string template using ${} interpolation syntax. Use the join() function or remove unnecessary interpolation syntax to fix it.

Quick fix

Fixes Error: Invalid template interpolation value

# Wrong - trying to interpolate a list directly
resource "example" "test" {
  config = "\${aws_subnet.example.*.id}"
}

# Wrong - using a null value in string
config = "\${var.optional_value}"

# Wrong - interpolating a map directly
output = "\${local.settings}"
  1. Identify the problematic interpolation in your configuration
  2. Use join() to convert lists to strings
  3. Handle null values with coalesce() or conditional logic
  4. Remove unnecessary interpolation syntax (Terraform 0.12+)
terraform — error
# Wrong - trying to interpolate a list directly
resource "example" "test" {
  config = "\${aws_subnet.example.*.id}"
}
# Wrong - using a null value in string
config = "\${var.optional_value}"
# Wrong - interpolating a map directly
output = "\${local.settings}"
Error: Invalid template interpolation value

What this error means

Terraform template interpolation has strict type requirements. When you use the ${} syntax to embed values in strings, Terraform expects those values to be strings or types that can be safely converted to strings. If you try to interpolate a list, tuple, map, or null value directly into a template, Terraform throws this error because these complex types cannot be automatically converted to strings. This commonly occurs after upgrading to Terraform v0.12+, which enforces stricter type checking than older versions. The error message may include details like "Cannot include the given value in a string template: string required" or "The expression result is null. Cannot include a null value in a string template."

Typical symptoms

  • Terraform apply/plan fails with 'Invalid template interpolation value' error
  • Error occurs when trying to use splat syntax (e.g., aws_subnet.*.id) in a string
  • Error happens when referencing variables that are lists, maps, or null values
  • Upgrading Terraform version causes previously working configs to fail

Common causes

  1. Attempting to interpolate a list or tuple directly into a string (most common). For example, using a splat operator result like aws_subnet.example.*.id in a template string.
  2. Trying to include a null value in a string template, often from optional attributes that are not set
  3. Using complex types (maps, objects) directly in template strings without converting them first
  4. Deprecated interpolation-only syntax from Terraform 0.11 or earlier that is incompatible with 0.12+

How to fix "Error: Invalid template interpolation value"

1Identify the problematic interpolation in your configuration

Review your Terraform configuration files (.tf files) and look for the error message location. The error will point to a specific line and resource. Common patterns to look for include:

hcl
# Wrong - trying to interpolate a list directly
resource "example" "test" {
  config = "\${aws_subnet.example.*.id}"
}

# Wrong - using a null value in string
config = "\${var.optional_value}"

# Wrong - interpolating a map directly
output = "\${local.settings}"

Check the error message in your terraform output to see exactly which line and attribute has the problem.

2Use join() to convert lists to strings

If you're trying to interpolate a list or splat expression, use the join() function to convert it to a comma-separated string:

hcl
# Right - join the list into a string
resource "example" "test" {
  config = join(",", aws_subnet.example.*.id)
}

# Right - or if you need it in a template, use join inside
message = "Subnets: \${join(", ", aws_subnet.example.*.id)}"

The join() function takes a delimiter (first argument) and a list (second argument) and combines them into a single string.

3Handle null values with coalesce() or conditional logic

If the error involves null values, use coalesce() to provide a default, or use a conditional expression:

hcl
# Right - provide a default if value is null
config = coalesce(var.optional_value, "default")

# Right - use conditional expression
config = var.optional_value != null ? var.optional_value : "default"

# Right - or simply omit the value if it's optional
optional_setting = var.optional_value

coalesce() returns the first non-null argument, making it useful for providing defaults.

4Remove unnecessary interpolation syntax (Terraform 0.12+)

If you're using Terraform 0.12 or newer, remove the ${} wrapper when a value is already an expression. This is a deprecated pattern from v0.11:

hcl
# Old style (Terraform 0.11) - now deprecated
instance_id = "\${aws_instance.example.id}"

# New style (Terraform 0.12+) - preferred
instance_id = aws_instance.example.id

In Terraform 0.12+, you can reference values directly without the interpolation syntax. Only use ${} when you actually need to embed an expression inside a string.

5For complex types, use jsonencode() or yamlencode()

If you need to convert maps, objects, or other complex types to strings for templates, use jsonencode() or yamlencode():

hcl
# Right - convert map to JSON string
config = jsonencode(var.settings)

# Right - convert to YAML if needed
yaml_config = yamlencode(var.settings)

# Right - combine with template if needed
message = "Config: \${jsonencode(local.settings)}"

These functions handle the serialization of complex types safely.

Advanced notes

Type Safety in Terraform v0.12+: Terraform v0.12 introduced stricter type checking compared to v0.11. The interpolation syntax ${} was overloaded in v0.11 to handle both string embedding and general expressions, but v0.12 separated these concerns. Now, ${} should only be used when you need to embed an expression within a string literal.

Escaping Dollar Signs: If you need a literal ${} in your output (for example, in a CloudFormation template or environment variable), use $${} (double dollar sign) to escape it:

hcl
config = "Use $${var_name} for substitution"  # Outputs: Use ${var_name}

Performance Consideration: When building complex strings from many interpolations, consider using templatefile() instead for better readability and performance:

hcl
config = templatefile("\${path.module}/config.tpl", {
  instances = aws_instance.example.*.id
})

Frequently asked questions

What does "Error: Invalid template interpolation value" mean?
Terraform template interpolation has strict type requirements. When you use the ${} syntax to embed values in strings, Terraform expects those values to be strings or types that can be safely converted to strings. If you try to interpolate a list, tuple, map, or null value directly into a template, Terraform throws this error because these complex types cannot be automatically converted to strings.
How do I fix "Error: Invalid template interpolation value"?
This error occurs when you try to include a non-string value (like a list or tuple) directly in a string template using ${} interpolation syntax. Use the join() function or remove unnecessary interpolation syntax to fix it.
What causes "Error: Invalid template interpolation value"?
Attempting to interpolate a list or tuple directly into a string (most common). For example, using a splat operator result like aws_subnet.example.*.id in a template string. Trying to include a null value in a string template, often from optional attributes that are not set Using complex types (maps, objects) directly in template strings without converting them first
Is the "Error: Invalid template interpolation value" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading