mikefarah/yq · error

cannot match with %v, can only match strings. Hint: Most oft

Error message

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

What it means

match runs a regex against each matched node's value, which requires strings: the guard rejects any node whose resolved tag is not !!str (the tag is printed). As with sub, the hint notes that using plain '=' instead of '|=' is the most common reason the operator receives a non-string node in the first place.

Source

Thrown at pkg/yqlib/operator_strings.go:442

		regExStr = regExNodes.MatchingNodes.Front().Value.(*CandidateNode).Value
	}
	log.Debugf("regEx %v", regExStr)
	regEx, err := regexp.Compile(regExStr)
	return regEx, matchPrefs, err
}

func matchOperator(d *dataTreeNavigator, context Context, expressionNode *ExpressionNode) (Context, error) {
	regEx, matchPrefs, err := extractMatchArguments(d, context, expressionNode)
	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 match with %v, can only match strings. Hint: Most often you'll want to use '|=' over '=' for this operation", node.Tag)
		}

		match(matchPrefs, regEx, node, node.Value, results)
	}

	return context.ChildContext(results), nil
}

func captureOperator(d *dataTreeNavigator, context Context, expressionNode *ExpressionNode) (Context, error) {
	regEx, matchPrefs, err := extractMatchArguments(d, context, expressionNode)
	if err != nil {
		return Context{}, err
	}

	var results = list.New()

	for el := context.MatchingNodes.Front(); el != nil; el = el.Next() {
		node := el.Value.(*CandidateNode)

View on GitHub (pinned to 8b5af0694b)

Solutions

1. Use the update-assign form: .a |= match("x") rather than .a = match("x")
2. Convert with tostring before matching
3. Confirm the target field is a string and not null/number

When it happens

Trigger: Thrown at pkg/yqlib/operator_strings.go:442 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/4d0a2e4badcaf27e. Report an issue: GitHub.