mikefarah/yq · error

SETPATH: expected single value on RHS but found %v

Error message

SETPATH: expected single value on RHS but found %v

What it means

The value part (RHS after the semicolon) of SETPATH must evaluate to exactly one node per document, since that single node is assigned at the given path. This error is thrown when the value expression produces zero or multiple results for a candidate document.

Source

Thrown at pkg/yqlib/operator_path.go:80

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

	lhsTraversalTree := createTraversalTree(lhsPath, traversePreferences{}, false)

	assignmentOp := &Operation{OperationType: assignOpType}

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

		targetContextValue, err := d.GetMatchingNodes(context.SingleReadonlyChildContext(candidate), expressionNode.RHS.RHS)
		if err != nil {
			return Context{}, err
		}

		if targetContextValue.MatchingNodes.Len() != 1 {
			return Context{}, fmt.Errorf("SETPATH: expected single value on RHS but found %v", targetContextValue.MatchingNodes.Len())
		}

		rhsOp := &Operation{OperationType: referenceOpType, CandidateNode: targetContextValue.MatchingNodes.Front().Value.(*CandidateNode)}

		assignmentOpNode := &ExpressionNode{
			Operation: assignmentOp,
			LHS:       lhsTraversalTree,
			RHS:       &ExpressionNode{Operation: rhsOp},
		}

		_, err = d.GetMatchingNodes(context.SingleChildContext(candidate), assignmentOpNode)

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

	}
	return context, nil

View on GitHub (pinned to 8b5af0694b)

Solutions

1. Wrap the value with an aggregator that yields one result: '.items | first', '(.items[]) as such — use [ ... ] | first' or '... // "default"'
2. Use a scalar/construct expression: 'SETPATH(["a"]; [.items[]])' assigns the whole array as one value
3. Verify the value expression returns exactly one node with 'yq '<expr> | length''

Example fix

// before
yq 'SETPATH(["names"]; .people[].name)' f.yml   // multiple results
// after
yq 'SETPATH(["names"]; [.people[].name])' f.yml  // single array value

yq '<valueExpr> | length' f.yml  # must print exactly 1 per document

yq 'select((<valueExpr> | length) == 1)' f.yml

// shell
out=$(yq 'SETPATH(["a"]; .items[])' f.yml 2>&1) || { echo "RHS not single: $out"; exit 1; }

When it happens

Trigger: 'SETPATH(["a"]; .items[])' where .items has 0 or many elements, 'SETPATH(["a"]; .missing[])' (0 results), or any iterator/optional expression on the value side.

Common situations: Value expressions using .[] or select that fan out or match nothing, documents with unexpected shapes (empty arrays), scripts ported from contexts where multi-value assignment was fine (plain '=' behaves differently).

Related errors

• SETPATH: expected single path but found %v results instead
• %v: expected path array, but got %v instead
• %v: could not parse %v as an int: %w
• %v: expected either a !!str or !!int in the path, found %v i
• DELPATHS: expected single value but found %v

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