What causes "DELPATHS: expected single value but found %v" in mikefarah/yq?

Ensure the argument yields a single array: 'delpaths([ ["a"], ["b"] ])'

DELPATHS: expected single value but found %v

Error message

DELPATHS: expected single value but found %v

What it means

DELPATHS takes exactly one argument: a single array of path arrays (e.g. [["a","b"], ["c"]]). This error is thrown when the RHS expression evaluates to a number of results other than 1 (0 if it matches nothing, >1 if it fans out), before the sequence-of-sequences check happens.

Source

Thrown at pkg/yqlib/operator_path.go:110

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

	}
	return context, nil
}

func delPathsOperator(d *dataTreeNavigator, context Context, expressionNode *ExpressionNode) (Context, error) {
	log.Debugf("delPaths")
	// single RHS expression that returns an array of paths (array of arrays)

	pathArraysContext, err := d.GetMatchingNodes(context.ReadOnlyClone(), expressionNode.RHS)
	if err != nil {
		return Context{}, err
	}
	if pathArraysContext.MatchingNodes.Len() != 1 {
		return Context{}, fmt.Errorf("DELPATHS: expected single value but found %v", pathArraysContext.MatchingNodes.Len())
	}
	pathArraysNode := pathArraysContext.MatchingNodes.Front().Value.(*CandidateNode)

	if pathArraysNode.Tag != "!!seq" {
		return Context{}, fmt.Errorf("DELPATHS: expected a sequence of sequences, but found %v", pathArraysNode.Tag)
	}

	updatedContext := context

	for i, child := range pathArraysNode.Content {

		if child.Tag != "!!seq" {
			return Context{}, fmt.Errorf("DELPATHS: expected entry [%v] to be a sequence, but its a %v. Note that delpaths takes an array of path arrays, e.g. [[\"a\", \"b\"]]", i, child.Tag)
		}
		childPath, err := getPathArrayFromNode("DELPATHS", child)

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

View on GitHub (pinned to 8b5af0694b)

Solutions

Ensure the argument yields a single array: 'delpaths([ ["a"], ["b"] ])'
Collapse multiple results into one: 'delpaths([.paths[]])' wraps elements into one array
Use 'first' or select to reduce the expression to a single match

Example fix

// before
yq 'delpaths(.toDelete[])' f.yml   // multiple results
// after
yq 'delpaths([.toDelete[]])' f.yml

Defensive patterns

Strategy: validation

Validate before calling

yq '<expr> | length' f.yml  # must print exactly 1
yq '<expr> | tag' f.yml     # must print !!seq

Type guard

yq 'select((<expr> | length) == 1 and (<expr> | tag) == "!!seq")' f.yml

Try / catch

// shell
out=$(yq 'delpaths(.p[])' f.yml 2>&1) || { echo "delpaths arg invalid: $out"; exit 1; }

Prevention

Always pass one array of path arrays: delpaths([["a"],["b"]])
Wrap iterators: [expr] to collapse multiple results into one
Verify the argument with '| length' and '| tag' first

When it happens

Trigger: 'delpaths(.paths[])' (iterator -> many results), 'delpaths(.missing)' on documents where the expression yields null/nothing, or an expression with multiple outputs.

Common situations: Forgetting the array-of-arrays structure and passing an iterator, documents where the paths variable is absent, expressions ported from jq where delpaths also expects exactly one argument but failure modes differ.

Related errors

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