hashicorp/terraform · error

[ ]

Error message

[%s] %s

What it means

Wrapper error produced by requiresReplacePath when translating a flatmap RequiresReplace key into a cty.Path fails. The original underlying error (from pathFromFlatmapKeyObject and friends) is preserved and shown after the flatmap key, so callers can identify both which attribute path was requested and why it could not be parsed.

Solutions

1. Read the wrapped error after the colon — it identifies the specific parsing failure (attribute not found, index out of range, etc.) and is the real cause.
2. Cross-reference the flatmap key against the current schema attribute names; rename or remove stale RequiresReplace entries.
3. Regenerate the diff with the current provider version so RequiresReplace reflects the live schema.
4. If the underlying error is 'attribute not found' (see [853]), the fix is to update the schema's RequiresReplace list.

Example fix

// before: schema lists RequiresReplace for a renamed attribute
//   RequiresReplace: []string{"legacy_name"}
//
// after:
//   RequiresReplace: []string{"new_name"}

path, err := requiresReplacePath(k, ty)
if err != nil {
    // err already includes the flatmap key prefix '[<k>]'; surface it as a
    // schema/diff mismatch for the user, and skip this RequiresReplace entry.
    log.Printf("[WARN] ignoring malformed RequiresReplace key %q: %v", k, err)
    continue
}

When it happens

Trigger: Calling requiresReplacePath(k, ty) where k is a flatmap-style key for a RequiresReplace attribute and ty is the resource's object type. Failure means the key does not correspond to a navigable attribute path inside ty (e.g. it references an attribute that does not exist, or contains a malformed index segment).

Common situations: A provider's schema lists RequiresReplace on an attribute name that has since been renamed/removed; state or schema migration left stale RequiresReplace entries; a custom diff producer emits a flatmap key with a typo or wrong separator.

Related errors

• attribute not found
• index out of range in %#v
• invalid step with type %#v
• unrecognized type
• cannot decode from flatmap

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

Appendix: 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 d32a084675)