mikefarah/yq · error

%v (%v) cannot modulo by %v (%v)

Error message

%v (%v) cannot modulo by %v (%v)

What it means

The modulo operator short-circuits when the left-hand tag is !!null, mirroring divide: 'null % n' is undefined, so it errors naming both operands and their paths. In practice the LHS expression matched a missing or null field.

Source

Thrown at pkg/yqlib/operator_modulo.go:18

package yqlib

import (
	"fmt"
	"math"
	"strconv"
	"strings"
)

func moduloOperator(d *dataTreeNavigator, context Context, expressionNode *ExpressionNode) (Context, error) {
	log.Debugf("Modulo operator")

	return crossFunction(d, context.ReadOnlyClone(), expressionNode, modulo, false)
}

func modulo(_ *dataTreeNavigator, _ Context, lhs *CandidateNode, rhs *CandidateNode) (*CandidateNode, error) {
	if lhs.Tag == "!!null" {
		return nil, fmt.Errorf("%v (%v) cannot modulo by %v (%v)", lhs.Tag, lhs.GetNicePath(), rhs.Tag, rhs.GetNicePath())
	}

	target := lhs.CopyWithoutContent()

	if lhs.Kind == ScalarNode && rhs.Kind == ScalarNode {
		if err := moduloScalars(target, lhs, rhs); err != nil {
			return nil, err
		}
	} else {
		return nil, fmt.Errorf("%v (%v) cannot modulo by %v (%v)", lhs.Tag, lhs.GetNicePath(), rhs.Tag, rhs.GetNicePath())
	}

	return target, nil
}

func moduloScalars(target *CandidateNode, lhs *CandidateNode, rhs *CandidateNode) error {
	lhsTag := lhs.Tag
	rhsTag := rhs.guessTagFromCustomType()

View on GitHub (pinned to 8b5af0694b)

Solutions

1. Guard the LHS: select(. != null) % 2
2. Provide a default: (.n // 0) % 2
3. Ensure the field exists in the input document

When it happens

Trigger: Thrown at pkg/yqlib/operator_modulo.go:18 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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