mikefarah/yq · error

aborted

Error message

aborted

What it means

This is not an internal fault: yq's `error` operator deliberately aborts expression evaluation and returns an error whose message is the operator's RHS value (defaulting to "aborted" when the RHS produces no nodes). It is yq's equivalent of `error`/`throw` in other languages, so any expression like `... || error("msg")` surfaces this error when the guard condition fails.

Source

Thrown at pkg/yqlib/operator_error.go:19

package yqlib

import (
	"errors"
)

func errorOperator(d *dataTreeNavigator, context Context, expressionNode *ExpressionNode) (Context, error) {

	log.Debugf("errorOperation")

	rhs, err := d.GetMatchingNodes(context.ReadOnlyClone(), expressionNode.RHS)
	if err != nil {
		return Context{}, err
	}
	errorMessage := "aborted"
	if rhs.MatchingNodes.Len() > 0 {
		errorMessage = rhs.MatchingNodes.Front().Value.(*CandidateNode).Value
	}
	return Context{}, errors.New(errorMessage)
}

View on GitHub (pinned to 8b5af0694b)

Solutions

1. Read the error message as data from your expression — fix the underlying condition that made the guard fire (e.g. the missing key or null value).
2. If 'aborted' appears with no detail, add an explicit message: replace bare `error` with `error("descriptive message")`.
3. If the abort is unintended, restructure the expression (e.g. use `// .fallback` instead of `// error(...)`) so the failing path is not taken.
4. Catch the error at the process level (non-zero exit code) and handle it in the surrounding script if it is an expected validation failure.

Example fix

// before: unhelpful message when value missing
./yq '.value // error' file.yaml
// error: aborted
// after: provide a clear message and a default path
./yq '.value // error(".value is required")' file.yaml

// Pre-check the guard condition so error() never fires unexpectedly:
yq '.value != null' file.yaml || echo "value missing"

// Go: detect an error-operator abort by message
classifier := func(err error) bool {
    return err != nil && (err.Error() == "aborted" || strings.HasPrefix(err.Error(), "error op"))
}

// Go API
out, err := navigator.GetMatchingNodes(ctx, expr)
if err != nil {
    if err.Error() == "aborted" || isMyValidationMessage(err) {
        // handle expected validation abort
        return handleAbort(err)
    }
    return err
}

When it happens

Trigger: An expression using the `error` operator executes, e.g. `.foo == null and error("foo is missing")` or `.x // error`, and either the RHS evaluates to a node whose Value becomes the message, or the RHS is empty (message defaults to "aborted").

Common situations: Validation-style yq pipelines in CI that intentionally fail when data is missing or invalid; copying examples with `// error("...")` where the left side unexpectedly yields null; running `error` with no argument and wondering why the message is just 'aborted'.

Related errors

• unknown operator %v
• no support for input format
• unrecognised type :( %v
• orderedMap: invalid yaml node
• system operator: command expression returned no results

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