What causes "cannot pivot node of type %v" in mikefarah/yq?

Select the array field first: `.rows | pivot(.x)` instead of `. | pivot(.x)` when root is a map.

cannot pivot node of type %v

Error message

cannot pivot node of type %v

What it means

`pivot` is only defined on sequence nodes; this top-level check rejects any candidate whose tag is not `!!seq`. The error names the actual tag so you can see whether you applied pivot to a map, scalar or other node.

Source

Thrown at pkg/yqlib/operator_pivot.go:103

	}
	result := CandidateNode{Kind: MappingNode}
	for _, k := range keys {
		pivotRow := CandidateNode{Kind: SequenceNode}
		pivotRow.AddChildren(
			pad(m[k], sz, nullNodeFactory))
		result.AddKeyValueChild(createScalarNode(k, k), &pivotRow)
	}
	return &result
}

func pivotOperator(_ *dataTreeNavigator, context Context, _ *ExpressionNode) (Context, error) {
	log.Debug("Pivot")
	results := list.New()

	for el := context.MatchingNodes.Front(); el != nil; el = el.Next() {
		candidate := el.Value.(*CandidateNode)
		if candidate.Tag != "!!seq" {
			return Context{}, fmt.Errorf("cannot pivot node of type %v", candidate.Tag)
		}
		tag, err := getUniqueElementTag(candidate)
		if err != nil {
			return Context{}, err
		}
		var pivot *CandidateNode
		switch tag {
		case "!!seq":
			pivot = pivotSequences(candidate)
		case "!!map":
			pivot = pivotMaps(candidate)
		default:
			return Context{}, fmt.Errorf("can only pivot elements of !!seq or !!map types, received %v", tag)
		}
		results.PushBack(pivot)
	}
	return context.ChildContext(results), nil
}

View on GitHub (pinned to 8b5af0694b)

Solutions

Select the array field first: `.rows | pivot(.x)` instead of `. | pivot(.x)` when root is a map.
Verify the target is an array with `tag` before pivoting.
If the data is a map, convert or extract its values into a sequence first (e.g. `.[]` / `to_entries`).
Check the reported tag in the message and adjust the path expression.

Example fix

// before
yq 'pivot(.id)' file.yml      # root is a map
// after
yq '.items | pivot(.id)' file.yml

Defensive patterns

Strategy: type-guard

Validate before calling

yq -e 'tag == "!!seq"' <<< "$node" || echo "pivot requires an array"

Type guard

isSeq() { [ "$(yq 'tag == "!!seq"' <<< "$1")" = "true" ]; }

Try / catch

out=$(yq '.items | pivot(.id)' file.yml 2>&1) || { echo "$out"; echo "pivot only works on arrays — select the array field first"; }

Prevention

Always select the array field before pivot, not its parent object.
Check the target's tag with yq 'tag' before pivoting.
For maps, extract values into a sequence first.
Watch for schema drift where array fields become objects.

When it happens

Trigger: Running `yq 'pivot(.a)'` where the selected node is a map or scalar instead of an array; applying pivot at the root of an object document.

Common situations: Misremembering pivot as working on maps directly; selecting the wrong key (the container object rather than its array field); schema drift where a field changed from array to object.

Related errors

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