can only pivot elements of !!seq or !!map types, received %v

Error message

can only pivot elements of !!seq or !!map types, received %v

What it means

After confirming the candidate is a sequence, pivot inspects the common element tag: elements must themselves be sequences or maps to be pivoted. If the unique element tag is anything else (e.g. all scalars), this error is thrown. yq cannot pivot flat scalar lists because there is no key/structure to pivot on.

Source

Thrown at pkg/yqlib/operator_pivot.go:116

	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

Pivot sequences of maps or sequences only: `[{k: 1}, {k: 2}] | pivot(.k)`.
Wrap scalars into objects first, e.g. `map({value: .}) | pivot(.value)`.
If you intended a different transformation on scalar lists, use `group_by`, `sort`, or `reverse` instead of pivot.
Check element tags with `[.[] | tag] | unique` before pivoting.

Example fix

// before
yq '[1, 2, 3] | pivot(.)' file.yml
// after
yq '[1, 2, 3] | map({value: .}) | pivot(.value)' file.yml

Defensive patterns

Strategy: validation

Validate before calling

yq -e 'tag == "!!seq" and ([.[] | tag] | unique | . == ["!!map"] or . == ["!!seq"])' <<< "$seq" || echo "pivot elements must all be maps or all sequences"

Type guard

isPivotable() { [ "$(yq '[.[] | tag] | unique | ( . == ["!!map"] or . == ["!!seq"] )' <<< "$1")" = "true" ]; }

Try / catch

out=$(yq 'pivot(.k)' file.yml 2>&1) || { echo "$out"; echo "scalar lists need wrapping: map({value: .})"; }

Prevention

Pivot only lists of objects or lists — never flat scalar lists.
Wrap scalars first: map({value: .}).
Verify element tags before pivoting.
Consider group_by/sort for flat-list transformations instead of pivot.

When it happens

Trigger: `yq '[1, 2, 3] | pivot(.)'` — a sequence of scalars; a sequence whose elements are all strings or numbers.

Common situations: Trying to pivot a flat list of values instead of objects/arrays; missing a mapping step that should wrap scalars into objects; loading data where records degenerated to scalars.

Related errors

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