How to fix Error: Cannot use element on an empty tuple in Terraform

TerraformINTERMEDIATEMEDIUMUpdated Dec 31, 2025· 138 views

The Terraform element() function fails when applied to empty lists or tuples. This error commonly occurs when conditional logic causes data sources or resource counts to return zero results.

Quick fix

Fixes Error: Cannot use element on an empty tuple

locals {
  first_subnet = try(element(aws_subnet.public[*].id, 0), null)
}
  1. Use the try() function to handle empty lists safely
  2. Add conditional length checks before using element()
  3. Use one() function for single-element lists
  4. Use coalescelist() to provide default values
terraform — error
locals {
  first_subnet = try(element(aws_subnet.public[*].id, 0), null)
}
Error: Cannot use element on an empty tuple

What this error means

In Terraform, the element(list, index) function retrieves a single element from a list using zero-based indexing. The error occurs because element() cannot safely access indices from an empty list—there are no elements to retrieve. This typically happens when: 1. A data source query returns no results 2. A count conditional evaluates to 0, creating no resources 3. A variable contains an empty list by default Terraform evaluates all expressions during planning, so even if you guard with a conditional, both branches are still evaluated, causing the error.

Typical symptoms

  • terraform plan or apply fails with 'cannot use element function with an empty list' error
  • Error appears during function call evaluation, not resource creation
  • Conditional logic (ternary operators) with length checks still fail
  • Error references a specific resource or data source that returned zero results

Common causes

  1. Data source query filters return no results (e.g., subnet lookup with wrong filters)
  2. count conditional evaluates to 0, creating no resources, but code tries to reference them
  3. Variable defaults to empty list and code tries to access elements without checking length first
  4. Module input lists are incomplete or missing expected elements (e.g., only 3 subnets in 6 AZ region)
  5. Resource conditional prevents creation but downstream code assumes it exists

How to fix "Error: Cannot use element on an empty tuple"

1Use the try() function to handle empty lists safely

The try() function evaluates an expression and returns a fallback value if it errors. This is the recommended approach for Terraform 0.13+:

hcl
locals {
  first_subnet = try(element(aws_subnet.public[*].id, 0), null)
}

If element() fails (empty tuple), it returns null instead of erroring.

2Add conditional length checks before using element()

Explicitly check if the list has elements before accessing them:

hcl
subnet_id = length(local.subnets) > 0 ? element(local.subnets, 0) : null

Note: This may still error in some cases because Terraform evaluates both branches. Combine with try() for safety:

hcl
subnet_id = length(local.subnets) > 0 ? try(element(local.subnets, 0), null) : null
3Use one() function for single-element lists

If your list should only have one element, use the one() function instead:

hcl
locals {
  single_item = one(var.my_list)
}

one() returns the single element if the list has exactly one item, or errors if empty or has multiple items.

4Use coalescelist() to provide default values

Replace empty lists with defaults using coalescelist():

hcl
locals {
  effective_list = coalescelist(var.my_list, ["default_value"])
  first = element(local.effective_list, 0)
}

This ensures element() always receives a non-empty list.

5Verify data source filters return results

Check that your data source query filters are correct and actually match resources:

hcl
data "aws_subnets" "available" {
  filter {
    name   = "vpc-id"
    values = [aws_vpc.main.id]  # Ensure VPC exists first
  }
}

# Only reference if subnets were found
resource "aws_nat_gateway" "example" {
  count         = length(data.aws_subnets.available.ids) > 0 ? 1 : 0
  subnet_id     = try(element(data.aws_subnets.available.ids, 0), null)
  allocation_id = aws_eip.nat[0].id
}
6Switch from count to for_each with dynamic resources

Instead of using count with element(), consider for_each which naturally handles empty collections:

hcl
locals {
  subnets = {
    for subnet in var.subnets : subnet.name => subnet
  }
}

resource "aws_route" "example" {
  for_each = local.subnets

  route_table_id = aws_route_table.main.id
  # Direct iteration avoids element() entirely
}

Advanced notes

In modules like terraform-aws-vpc, this error often occurs when availability zones don't match the number of subnet configurations (e.g., 6 AZs but only 3 subnet sets). The workaround is to either add dummy elements to lists or redesign iteration to use resource counts instead of AZ iteration.

Teraform's early evaluation of all branches in conditional expressions means ternary operators alone won't prevent this error—always combine length checks with try() for reliability.

For null providers and dynamic resources, prefer using dynamic blocks or for_each over conditional element() calls.

Frequently asked questions

What does "Error: Cannot use element on an empty tuple" mean?
In Terraform, the element(list, index) function retrieves a single element from a list using zero-based indexing. The error occurs because element() cannot safely access indices from an empty list—there are no elements to retrieve. This typically happens when: 1.
How do I fix "Error: Cannot use element on an empty tuple"?
The Terraform element() function fails when applied to empty lists or tuples. This error commonly occurs when conditional logic causes data sources or resource counts to return zero results.
What causes "Error: Cannot use element on an empty tuple"?
Data source query filters return no results (e.g., subnet lookup with wrong filters) count conditional evaluates to 0, creating no resources, but code tries to reference them Variable defaults to empty list and code tries to access elements without checking length first
Is the "Error: Cannot use element on an empty tuple" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading