In this article, we will take a look at the Terraform collection function, coalesce. We will explain what it is, what you might use it for, and how it compares to the similarĀ tryĀ function, before running through a few examples of its use.
The Terraform language includes many built-in functions you can call from within expressions to transform and combine values.
TheĀ coalesce function is categorized as a ācollectionā function ā in Terraform, a collection function refers to functions that operate on collections of values, such as lists, maps, or sets. These functions are used to manipulate and transform data within your Terraform configurations.
The Terraform coalesce function takes any number of arguments and returns the first one that isn’t null or an empty string. It is useful when you need to provide defaults, set missing values, or prioritize different value sources.
Note:
- All arguments to Terraform
coalesceĀ must be of the same type. Terraform will attempt conversions, but mismatched types can lead to errors. coalesceĀ checks arguments one by one until it finds a non-null or non-empty string. If none are found, it returns null.coalesceĀ isn’t a substitute for proper validation and handling of missing data. Use it strategically to make your configurations more concise and robust.
A similar function Terraform coalescelistĀ is available that performs a similar operation with list arguments rather than individual arguments.
Terraform coalesce vs try
The Terraform tryĀ function executes a sequence of expressions and returns the first one that doesnāt produce an error. It works by trying each expression in order and returning the successful result.
Where Terraform coalesce is more suited for setting default values for optional strings, the try function’s purpose is to run expressions and handle errors. coalesceĀ is used for simple defaults and missing attributes, whereĀ tryĀ is used where conditional logic is required and for handling failures. coalesce has no error handling abiltity.
Example 1: Setting defaults
One of the main uses for Terraform coalese is to set defaults. In the example below, the name for an AWS instance has an optional variable calledĀ user_defined_name. If it is not supplied, coalesceĀ is used to provide a default ofĀ my-generic-instance-name.
resource "aws_instance" "my_instance" {
name = coalesce(var.user_defined_name, "my-generic-instance-name")
...
}Example 2: Providing missing values
Another useful application of theĀ coalesceĀ function is to provide missing values.
In the example below, we query an API, which may or may not provide a description for a record with a given name.Ā coalesce can be used to avoid errors caused by missing attributes and ensures you still have a valid value for the resource propertyĀ description.
data "external" "my_data" {
name = "some_api"
...
}
resource "my_resource" "my_resource" {
name = data.external.my_data.id
description = coalesce(data.external.my_data.description, "No description available")
...
}Example 3: Prioritizing different value sources
Lastly,Ā coalesceĀ can be used to prioritize different value sources. For instance, you might prefer a user-defined configuration file over environment variables.
In the example below, ifĀ config.jsonĀ definesĀ my_setting, it takes precedence. Otherwise, the environment variable is checked, and finally, the default value is used if neither is present.
config_file_value = file("config.json").my_setting
environment_value = var.environment_settings.my_setting
setting = coalesce(config_file_value, environment_value, "default_value")Example 4: Experimenting with terraform console
Donāt forget you can also fire up theĀ terraform consoleĀ to experiment with theĀ coalesceĀ function.
Here, ālukeā is returned because it is the first one that is not null or an empty string:
Here, ādarthā is returned because the first value supplied is an empty string:
Here, ādarthā is returned because the first value supplied isĀ nullĀ :
Terraform Ā coalesce function takes any number of arguments and returns the first one that isn’t null or an empty string, making it a useful option when working with optional values and setting defaults.
We encourage you also to exploreĀ how Spacelift makes it easy to work with Terraform. If you need any help managing your Terraform infrastructure, building more complex workflows based on Terraform, and managing AWS credentials per run, instead of using a static pair on your local machine,Ā SpaceliftĀ is a fantastic tool for this.
Note: New versions of Terraform are placed under the BUSL license, but everything created before version 1.5.x stays open-source. OpenTofu is an open-source version of Terraform that expands on Terraformās existing concepts and offerings. It is a viable alternative to HashiCorpās Terraform, being forked from Terraform version 1.5.6.
Manage Terraform Better with Spacelift
Build more complex workflows based on Terraform using policy as code, programmatic configuration, context sharing, drift detection, resource visualization and many more.
HashiCorp Developer | Terraform Docs. coalesce – Functions – Configuration Language. Accessed: 21 October 2025
HashiCorp Developer | Terraform Docs. coalescelist – Functions – Configuration Language. Accessed: 21 October 2025
HashiCorp Developer | Terraform Docs. try – Functions – Configuration Language. Accessed: 21 October 2025
