mikefarah/yq · error

cannot substitute with %v, can only substitute strings. Hint

Error message

cannot substitute with %v, can only substitute strings. Hint: Most often you'll want to use '|=' over '=' for this operation

What it means

substitute (sub) needs a string to run the regex replacement over; the per-node guard checks guessTagFromCustomType() != "!!str" and rejects the first non-string. The hint in the message points at the other common cause of seeing this: using '=' instead of '|=' makes the RHS context the whole node rather than the field's string value.

Source

Thrown at pkg/yqlib/operator_strings.go:263

	block := expressionNode.RHS

	regExStr, replacementText, err := getSubstituteParameters(d, block, context)

	if err != nil {
		return Context{}, err
	}

	regEx, err := regexp.Compile(regExStr)
	if err != nil {
		return Context{}, err
	}

	var results = list.New()

	for el := context.MatchingNodes.Front(); el != nil; el = el.Next() {
		node := el.Value.(*CandidateNode)
		if node.guessTagFromCustomType() != "!!str" {
			return Context{}, fmt.Errorf("cannot substitute with %v, can only substitute strings. Hint: Most often you'll want to use '|=' over '=' for this operation", node.Tag)
		}

		result := node.CreateReplacement(substitute(node.Value, regEx, replacementText))
		results.PushBack(result)
	}

	return context.ChildContext(results), nil

}

func addMatch(original []*CandidateNode, match string, offset int, name string) []*CandidateNode {

	newContent := append(original,
		createScalarNode("string", "string"))

	if offset < 0 {
		// offset of -1 means there was no match, force a null value like jq
		newContent = append(newContent,

View on GitHub (pinned to 8b5af0694b)

Solutions

1. Use the update-assign form: .a |= sub("x", "y") instead of .a = sub("x", "y")
2. Convert to string: . | tostring | sub(...)
3. Ensure the target field is actually a string (not null/number)

When it happens

Trigger: Thrown at pkg/yqlib/operator_strings.go:263 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of mikefarah/yq@8b5af0694b (2026-09-05). Data as JSON: /api/errors/5a22d6fb8d8e4489. Report an issue: GitHub.