mikefarah/yq · error

%v: expected path array, but got %v instead

Error message

%v: expected path array, but got %v instead

What it means

SETPATH and DELPATHS expect their path expression to evaluate to a sequence (array), whose elements are path keys/indices. getPathArrayFromNode checks node.Kind == SequenceNode and throws this error (prefixed with SETPATH or DELPATHS) when the expression instead produced a scalar, map, or null — the %v is the node's YAML tag (e.g. !!str, !!map, !!null).

Source

Thrown at pkg/yqlib/operator_path.go:19

package yqlib

import (
	"container/list"
	"fmt"
)

func createPathNodeFor(pathElement interface{}) *CandidateNode {
	switch pathElement := pathElement.(type) {
	case string:
		return &CandidateNode{Kind: ScalarNode, Value: pathElement, Tag: "!!str"}
	default:
		return &CandidateNode{Kind: ScalarNode, Value: fmt.Sprintf("%v", pathElement), Tag: "!!int"}
	}
}

func getPathArrayFromNode(funcName string, node *CandidateNode) ([]interface{}, error) {
	if node.Kind != SequenceNode {
		return nil, fmt.Errorf("%v: expected path array, but got %v instead", funcName, node.Tag)
	}

	path := make([]interface{}, len(node.Content))

	for i, childNode := range node.Content {
		switch childNode.Tag {
		case "!!str":
			path[i] = childNode.Value
		case "!!int":
			number, err := parseInt(childNode.Value)
			if err != nil {
				return nil, fmt.Errorf("%v: could not parse %v as an int: %w", funcName, childNode.Value, err)
			}
			path[i] = number
		default:
			return nil, fmt.Errorf("%v: expected either a !!str or !!int in the path, found %v instead", funcName, childNode.Tag)
		}

View on GitHub (pinned to 8b5af0694b)

Solutions

1. Wrap path elements in an array: 'SETPATH(["a", "b"]; value)'
2. Check what the path expression returns ('yq '<expr> | tag'') and fix it to yield a !!seq
3. If the path may be missing, guard with select/alternative so a valid array is always produced

Example fix

// before
yq 'SETPATH("a"; 3)' f.yml
// after
yq 'SETPATH(["a"]; 3)' f.yml

yq '<pathExpr> | tag' f.yml  # must print !!seq
type guard: yq 'select((<pathExpr> | tag) == "!!seq") | SETPATH(<pathExpr>; v)' f.yml

yq 'select((.p | tag) == "!!seq") | SETPATH(.p; 3)' f.yml

// shell
out=$(yq 'SETPATH(.p; 3)' f.yml 2>&1) || { echo "SETPATH failed: $out"; exit 1; }

When it happens

Trigger: SETPATH with a non-array first argument: 'SETPATH("a"; "v")' or 'SETPATH(.someMap; 3)', or DELPATHS('a, b') passing a scalar instead of an array of path arrays. Also when the path expression matches nothing and returns null ('!!null').

Common situations: Hand-written paths missing the surrounding [] brackets, refactored scripts where the path expression was changed to a scalar, expressions returning null because the document shape differs from expectations.

Related errors

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

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