Skip to main content
DevOps Insightsguides & answers

Terraform · troubleshooting

Error: Invalid index

An expression asked for list item N, a map key, or resource [0], and that element does not exist. Usually a list shorter than expected, a missing map key, or a resource whose count is 0.

Reproduced on Terraform 1.14.0, . Where the text says “reproduced”, the behaviour was run on that version, not taken from documentation.

First published

New to this? Read what is actually happening first, then come back to the steps.

On this page · 8 sections

Before you start

  • The file and line in the error, and the variable or resource it names.

Run this first

step 1 of 1
terraform console

Look for length(…) or keys(…) of the collection in the error

Evaluates expressions with the real variables and state, so you can see the length or keys Terraform sees.

Work out which cause you have

A few questions to narrow the list. Every answer ends in a command that confirms or rules the cause out — this cannot see your cluster, so nothing here is a certainty until you have checked.

Narrow it down

0 answered · nothing is sent anywhere

What does the error box say about the value?

Cause space

3 of 3 still possible

  • The list has fewer items than the indexCommon
  • The map has no such keyCommon
  • The resource has count = 0Common

Nothing ruled out yet. Answer the question above and the branches your answer eliminates will strike through here.

Or diagnose it manually

In this order. The first command usually contains the whole answer.

  1. Step 1

    terraform console

    Evaluates expressions with the real variables and state, so you can see the length or keys Terraform sees.

    Look for length(…) or keys(…) of the collection in the error

Every cause, and how to fix it

Ordered by how often each one turns out to be the answer.

The list has fewer items than the index

Common

Two subnets assumed, one supplied; a data source that returned fewer results in this region or account.

Confirm

echo 'length(var.subnets)' | terraform console

A length less than or equal to the index used

Fix

  • Pass the values the configuration expects, or iterate over what exists with for_each or count = length(…) instead of fixed positions.
  • If the item is genuinely optional: try(var.subnets[1], null).

The map has no such key

Common

A per-region or per-environment map without an entry for the one in use.

Confirm

echo 'keys(var.amis)' | terraform console

The key from the error not in the list

Fix

  • Add the missing entry, or give a default: lookup(var.amis, var.region, "DEFAULT").
  • Better, reject the input early: a validation block with condition = contains(keys(var.amis), var.region) stopped plan with its own message on Terraform 1.14.0.
ami = lookup(var.amis, var.region, "ami-default")

Reproduced on Terraform 1.14.0: lookup with a default planned where the index failed.

The resource has count = 0

Common

A resource switched off with count = var.enabled ? 1 : 0 is still referenced as resource[0] elsewhere.

Confirm

terraform plan

RESOURCE is empty tuple in the error box

Fix

  • Use one(): one(aws_instance.web[*].id) gives null when there are none and the value when there is one.
  • Or guard the reference with the same condition as the count.

Understanding it properly

Skip this if you are mid-incident — the working part of the page is above. Worth reading afterwards, because understanding the mechanism is what stops the next one.

In plain terms

Terraform found something like var.subnets[1] or aws_instance.web[0], but the list has fewer items, the map has no such key, or the resource was created zero times. Decide what should happen when the element is missing, and write that into the expression.

Words used on this page

Index
The position in a list, counted from 0, so [1] is the second item.
count = 0
A resource that is created zero times; referring to it gives an empty tuple, which has no [0].
What is actually happening

Reproduced on 23 October 2026 with Terraform 1.14.0 and terraform plan. Three shapes gave Error: Invalid index and exit 1: var.subnets[1] on a one-item list, var.amis["us-east-1"] on a map without that key, and terraform_data.web[0] on a resource with count = 0. The error box shows the value it had, for example var.subnets is list of string with 1 element, or terraform_data.web is empty tuple.

terraform validate passed the list case, because the list's length is only known with real values. Run plan in CI to catch this, not only validate.

Avoid element() as a fix: element(var.subnets, 1) on a one-item list returned the first item, because element wraps around past the end. The Terraform docs recommend list[index] in most cases for this reason.

How to tell this is your problem
WhereWhat you see
terraform plan or applyError: Invalid index … The given key does not identify an element in this collection value: the given index is greater than or equal to the length of the collection.
A resource with count = 0aws_instance.web is empty tuple … the collection has no elements.

How to know it is actually fixed

  • terraform plan completes without the error, with and without the optional element present.

Stopping it happening again

  • Iterate (for_each, for expressions) instead of picking fixed positions.
  • Add validation blocks for maps keyed by region or environment.
  • Run terraform plan in CI for each environment's variables; validate alone missed the list case.

Sources

Behaviour described here is drawn from official documentation. Where a figure could not be confirmed on an official page it is attributed in the text rather than stated as canonical.

Did this get you to an answer?

No text box on purpose — please do not paste production logs anywhere

Something wrong or out of date? Report it

Where to go next