hashicorp/terraform · error

[%s] %s

Error message

[%s] %s

What it means

Returned by requiresReplacePath (paths.go:93) as a wrapper around any error produced by pathFromFlatmapKeyObject while converting a flatmap key into a cty.Path for a resource attribute flagged RequiresReplace. The wrapper prepends the original flatmap key '[%s]' so the caller knows which attribute key triggered the inner failure (which will be one of attribute-not-found, invalid-step, unrecognized-type, or out-of-range).

Source

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

	return path
}

// requiresReplacePath takes a key from a flatmap along with the cty.Type
// describing the structure, and returns the cty.Path that would be used to
// reference the nested value in the data structure.
// This is used specifically to record the RequiresReplace attributes from a
// ResourceInstanceDiff.
func requiresReplacePath(k string, ty cty.Type) (cty.Path, error) {
	if k == "" {
		return nil, nil
	}
	if !ty.IsObjectType() {
		panic(fmt.Sprintf("requires replace path on non-object type: %#v", ty))
	}

	path, err := pathFromFlatmapKeyObject(k, ty.AttributeTypes())
	if err != nil {
		return path, fmt.Errorf("[%s] %s", k, err)
	}
	return path, nil
}

func pathSplit(p string) (string, string) {
	parts := strings.SplitN(p, ".", 2)
	head := parts[0]
	rest := ""
	if len(parts) > 1 {
		rest = parts[1]
	}
	return head, rest
}

func pathFromFlatmapKeyObject(key string, atys map[string]cty.Type) (cty.Path, error) {
	k, rest := pathSplit(key)

	path := cty.Path{cty.GetAttrStep{Name: k}}

View on GitHub (pinned to c9def3e214)

Solutions

1. Read the inner error (after the ']') — it is the root cause (e.g. 'attribute X not found'); fix that specific condition first.
2. Confirm the resource's current schema contains every attribute key mentioned in the RequiresReplace list.
3. If an attribute was renamed/removed, migrate state or re-apply to regenerate the diff under the new schema.
4. Pin provider versions so the planner and schema agree.

Example fix

// before — diff marks RequiresReplace on key 'old_name.0.value',
// but schema now calls it 'new_name'

// after — migrate state / re-apply so the diff uses the current attribute name

paths, err := hcl2shim.RequiresReplace(requiresReplaceAttrs, ty)
if err != nil {
    // the wrapped '[key] inner-error' tells you which diff key is stale;
    // fall back to replacing the whole resource rather than failing the plan
    log.Printf("[WARN] cannot map requires-replace attrs: %v; treating all as replace", err)
    return []cty.Path{{cty.GetAttrStep{Name: "__all__"}}}, nil
}

When it happens

Trigger: Terraform computes a resource instance diff where one or more attributes are marked as forcing replacement (RequiresNew). RequiresReplace then iterates those flatmap keys and calls requiresReplacePath; if any key cannot be mapped onto the resource's object type, the inner error is wrapped here.

Common situations: A diff contains a RequiresReplace flatmap key that does not correspond to any attribute in the current schema (schema drifted, or a computed/removed attribute got into the diff). Provider schema and state are out of sync. A planner emitted an unexpected key shape.

Related errors

• attribute %q not found
• index %s out of range in %#v
• wrong number of values for %q in state: got %d, but need %d
• invalid step %q with type %#v
• unrecognized type: %s

AI-assisted analysis of hashicorp/terraform@c9def3e214 (2026-08-07). Data as JSON: /api/errors/222477d2b19afd18. Report an issue: GitHub.