SETPATH: expected single path but found %v results instead

Error message

SETPATH: expected single path but found %v results instead

What it means

The first argument of SETPATH must evaluate to exactly one path array. This error reports how many results the LHS-of-semicolon expression produced when that count is not 1 (0 when the expression matches nothing, >1 when it fans out over multiple nodes).

Source

Thrown at pkg/yqlib/operator_path.go:57

	return path, nil
}

// SETPATH(pathArray; value)
func setPathOperator(d *dataTreeNavigator, context Context, expressionNode *ExpressionNode) (Context, error) {
	log.Debugf("SetPath")

	if expressionNode.RHS.Operation.OperationType != blockOpType {
		return Context{}, fmt.Errorf("SETPATH must be given a block (;), got %v instead", expressionNode.RHS.Operation.OperationType.Type)
	}

	lhsPathContext, err := d.GetMatchingNodes(context.ReadOnlyClone(), expressionNode.RHS.LHS)

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

	if lhsPathContext.MatchingNodes.Len() != 1 {
		return Context{}, fmt.Errorf("SETPATH: expected single path but found %v results instead", lhsPathContext.MatchingNodes.Len())
	}
	lhsValue := lhsPathContext.MatchingNodes.Front().Value.(*CandidateNode)

	lhsPath, err := getPathArrayFromNode("SETPATH", lhsValue)

	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 {

View on GitHub (pinned to 8b5af0694b)

Solutions

Select exactly one array: 'SETPATH(.paths | first; v)' or add select filters to narrow to one match
Use the array literal form 'SETPATH(["a","b"]; v)' so exactly one path array is produced
Check the path expression output count with 'yq '<expr> | length'' and fix the document/expression

Example fix

// before
yq 'SETPATH(.paths[]; "x")' f.yml    // multiple matches
// after
yq 'SETPATH(.paths | first; "x")' f.yml

Defensive patterns

Strategy: validation

Validate before calling

yq '<pathExpr> | length' f.yml  # must print exactly 1

Type guard

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

Try / catch

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

Prevention

Avoid iterators (.[]) in SETPATH path expressions
Use array literals or 'first' to guarantee one result
Check result counts with '| length' during script development

When it happens

Trigger: 'SETPPATH' with a path expression matching multiple nodes, e.g. 'SETPATH(.items[]; v)' or 'SETPATH(.a[], .b[]; ...)' style expressions, or matching nothing ('SETPATH(.nonexistent[]; v)' -> 0 results).

Common situations: Using wildcard/iterators (.[], .[]) in the path expression, documents whose shape differs from what the script assumed, missing 'first' to limit matches.

Related errors

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