What causes "item not found" in hashicorp/terraform?

Verify the value exists in the list (typo, case, whitespace).

item not found

Error message

item not found

What it means

Thrown by `index()` (IndexFunc) after iterating the entire list/tuple without finding an element equal (via stdlib.Equal) to the searched value. The list is non-empty and known, but no element matched. This is the 'not present' terminal state.

Solutions

Verify the value exists in the list (typo, case, whitespace).
Use `contains(var.list, val)` to pre-check membership before index().
Wrap with try() or guard the call if absence is expected.

Example fix

// before
locals { i = index(var.environments, var.target_env) }

// after
locals { i = contains(var.environments, var.target_env) ? index(var.environments, var.target_env) : -1 }

Defensive patterns

Strategy: validation

Validate before calling

# HCL: check membership before index
locals { i = contains(var.list, val) ? index(var.list, val) : -1 }

Type guard

# HCL: try-based fallback
locals { i = try(index(var.list, val), -1) }

Prevention

Use contains() before index() to avoid the not-found error.
Normalize string comparisons (trim, lower) to avoid silent mismatches.
Consider a map lookup when you only need the value, not its position.

When it happens

Trigger: Calling `index(["a","b"], "c")`. The searched value was never added to the list.

Common situations: Searching for a key/name that does not exist in the current state. Case mismatch, trailing whitespace, or type difference between the searched value and list elements causing all comparisons to fail.

Related errors

AI-assisted analysis of hashicorp/terraform@d32a084675 (2026-08-11). Data as JSON: /api/errors/13fc22fb738ad8ea. Report an issue: GitHub.

Appendix: source

Thrown at internal/lang/funcs/collection.go:217

		if args[0].LengthInt() == 0 { // Easy path
			return cty.NilVal, errors.New("cannot search an empty list")
		}

		for it := args[0].ElementIterator(); it.Next(); {
			i, v := it.Element()
			eq, err := stdlib.Equal(v, args[1])
			if err != nil {
				return cty.NilVal, err
			}
			if !eq.IsKnown() {
				return cty.UnknownVal(cty.Number), nil
			}
			if eq.True() {
				return i, nil
			}
		}
		return cty.NilVal, errors.New("item not found")

	},
})

// LookupFunc constructs a function that performs dynamic lookups of map types.
var LookupFunc = function.New(&function.Spec{
	Params: []function.Parameter{
		{
			Name:         "inputMap",
			Type:         cty.DynamicPseudoType,
			AllowMarked:  true,
			AllowUnknown: true,
		},
		{
			Name:         "key",
			Type:         cty.String,
			AllowMarked:  true,
			AllowUnknown: true,

View on GitHub (pinned to d32a084675)