How to Use Terraform concat Lists to Combine Multiple Lists in Terraform 0.12+

Terraform provides the built-in concat function to join multiple list values into a single ordered collection, evaluating arguments at plan time through the standard library's ConcatFunc implementation.

Terraform 0.12 introduced the cty type system and stabilized the concat function for merging collections within HashiCorp Configuration Language (HCL). When you need to combine lists, tuples, or sets into a single ordered list, concat provides a pure operation that executes during the planning phase. According to the hashicorp/terraform source code, this function is registered in internal/lang/functions.go at lines 96 and 307, delegating to stdlib.ConcatFunc.

How concat Is Implemented in Terraform

The concat function is registered in the language function map under the name concat within internal/lang/functions.go. According to the source analysis, lines 96 and 307 map this name to stdlib.ConcatFunc, which contains the actual implementation logic for merging collections.

When invoked, Terraform evaluates each argument and expects list-compatible values—specifically lists, tuples, or sets that can be converted to the cty.List type. The function performs the following operations:

• Converts all arguments to cty.List representations internally
• Returns a new cty.List whose element type is the most specific type capable of representing all input elements
• Executes as a pure function with no side effects, working entirely at plan time

If any argument cannot be converted to a list (such as a bare string or map), Terraform raises a runtime error indicating that a list type is expected.

Basic Syntax for Concatenating Two Lists

The concat function accepts two or more list arguments and returns a single ordered collection.

locals {
  list_a = ["a", "b"]
  list_b = ["c", "d"]
  combined = concat(local.list_a, local.list_b)
}

# Result: ["a", "b", "c", "d"]

Practical Examples for Infrastructure Code

Concatenating Lists with Sets

Terraform automatically converts sets to lists before concatenation, as handled by the standard library's type conversion logic:

variable "set_input" {
  type    = set(string)
  default = ["x", "y"]
}

locals {
  base   = ["p", "q"]
  result = concat(local.base, var.set_input)
}

# Result: ["p", "q", "x", "y"]

Merging Resource Attributes with Splat Expressions

Use concat to combine dynamic resource collections with static values:

resource "aws_subnet" "example" {
  count = 3
  # ... subnet configuration ...

}

output "subnet_ids" {
  value = concat(aws_subnet.example[*].id, ["static-id-1", "static-id-2"])
}

# Output contains IDs of all three subnets followed by static IDs

Handling Dynamic List Counts Using flatten

For scenarios involving nested lists or dynamic argument counts, combine concat with the expansion operator and flatten:

locals {
  groups = [
    ["g1a", "g1b"],
    ["g2a"],
    ["g3a", "g3b", "g3c"]
  ]

  all = flatten(concat(local.groups...))
}

# Result: ["g1a", "g1b", "g2a", "g3a", "g3b", "g3c"]

Error Handling and Type Constraints

As implemented in stdlib.ConcatFunc, the function strictly validates input types. The resulting list's element type is inferred as the most specific union type that can accommodate all input elements. Passing a non-list value—such as an individual string or number—triggers a type error during the expression evaluation phase, before Terraform creates or modifies any infrastructure resources.

Summary

• The concat function is registered in internal/lang/functions.go (lines 96 and 307) and implemented via stdlib.ConcatFunc in the hashicorp/terraform source
• Accepts lists, tuples, and sets, automatically converting compatible types to cty.List
• Returns a pure result at plan time with no side effects or resource dependencies
• Maintains element order based on argument position (first argument's elements appear first)
• Requires all arguments to be list-compatible; use brackets [ ] to wrap single items

Frequently Asked Questions

What is the difference between concat and merge in Terraform?

The concat function combines multiple lists into a single ordered list, preserving all elements including duplicates and maintaining sequence. In contrast, the merge function operates exclusively on maps or objects, combining key-value pairs where later arguments overwrite duplicate keys. You cannot use concat with maps or merge with lists, as their underlying implementations handle different cty types.

Can I use concat with more than two lists?

Yes. The concat implementation accepts a variable number of arguments, allowing you to concatenate three or more collections in a single invocation: concat(list_a, list_b, list_c, list_d). The standard library processes arguments sequentially from left to right, appending each collection's elements to the result in the order received.

Why does concat fail when I try to concatenate a string and a list?

Terraform's concat function strictly requires all arguments to be list-compatible types (lists, tuples, or sets). Single scalar values like strings cannot be automatically converted to lists. To include a single string in the concatenation, wrap it in square brackets to create a single-element list: concat(list_a, ["single-value"]).

Does concat preserve the order of elements?

Yes. According to the ConcatFunc implementation in the standard library, the function constructs the resulting list by iterating through input arguments in order and appending their elements sequentially. Elements from the first argument appear first, followed by elements from the second argument, ensuring stable ordering throughout the operation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}