hashicorp/terraform · error

index out of range in %#v

Error message

index %s out of range in %#v

What it means

Returned by pathFromFlatmapKeyTuple when the integer index parsed from the key is greater than or equal to the declared tuple arity (len(etys)). The decoder has already built the IndexStep but cannot resolve the element type for an out-of-bounds position, so it aborts with the offending key and element-type list for diagnostics.

Solutions

1. Cross-check the index in the error against the tuple's current element count.
2. If the tuple legitimately shrank, write a state upgrader and remove stale RequiresReplace entries.
3. Restore the schema/plan to a consistent version pair so indices align with arity.
4. If variable-length indexing is needed, model the field as a list rather than a positional tuple.

Example fix

// before: tuple arity 3, RequiresReplace references index 5
// after: align arity to 6, or drop the stale index-5 entry

func tupleIndexInRange(key string, arity int) bool {
    k, _ := pathSplit(key)
    idx, err := strconv.Atoi(k)
    if err != nil { return false }
    return idx >= 0 && idx < arity
}

func tupleIndexInRange(key string, arity int) bool {
    k, _ := pathSplit(key)
    idx, err := strconv.Atoi(k)
    if err != nil { return false }
    return idx >= 0 && idx < arity
}

When it happens

Trigger: Translating a flatmap key with an index segment (e.g. 'attr.5.sub') where the index exceeds the tuple's declared arity. Reached via requiresReplacePath or the pathFromFlatmapKey* family when descending into tuple-typed positions.

Common situations: Schema change that shrank a tuple's arity while old diffs/state still reference higher indices; RequiresReplace referencing an index that no longer exists; custom diff producers emitting indices past the end.

Related errors

• attribute not found
• invalid count value for
• invalid step with type %#v
• [ ]
• unrecognized type

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

Appendix: source

Thrown at internal/configs/hcl2shim/paths.go:177

	var path cty.Path
	var err error

	k, rest := pathSplit(key)

	// we don't need to convert the index keys to paths
	if k == "#" {
		return path, nil
	}

	idx, err := strconv.Atoi(k)
	if err != nil {
		return path, err
	}

	path = cty.Path{cty.IndexStep{Key: cty.NumberIntVal(int64(idx))}}

	if idx >= len(etys) {
		return path, fmt.Errorf("index %s out of range in %#v", key, etys)
	}

	if rest == "" {
		return path, nil
	}

	ty := etys[idx]

	p, err := pathFromFlatmapKeyValue(rest, ty.ElementType())
	if err != nil {
		return path, err
	}

	return append(path, p...), nil
}

func pathFromFlatmapKeyMap(key string, ty cty.Type) (cty.Path, error) {
	var path cty.Path

View on GitHub (pinned to d32a084675)