{"record":{"id":"f451f03366249899","repo":"mikefarah/yq","slug":"unknown-operator-v","errorCode":null,"errorMessage":"unknown operator %v","messagePattern":"unknown operator (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/yqlib/data_tree_navigator.go","lineNumber":66,"sourceCode":"\treturn err\n}\n\nfunc (d *dataTreeNavigator) GetMatchingNodes(context Context, expressionNode *ExpressionNode) (Context, error) {\n\tif expressionNode == nil {\n\t\tlog.Debugf(\"getMatchingNodes - nothing to do\")\n\t\treturn context, nil\n\t}\n\tlog.Debugf(\"Processing Op: %v\", expressionNode.Operation.toString())\n\tif log.IsEnabledFor(slog.LevelDebug) {\n\t\tfor el := context.MatchingNodes.Front(); el != nil; el = el.Next() {\n\t\t\tlog.Debug(NodeToString(el.Value.(*CandidateNode)))\n\t\t}\n\t}\n\thandler := expressionNode.Operation.OperationType.Handler\n\tif handler != nil {\n\t\treturn handler(d, context, expressionNode)\n\t}\n\treturn Context{}, fmt.Errorf(\"unknown operator %v\", expressionNode.Operation.OperationType.Type)\n\n}\n","sourceCodeStart":48,"sourceCodeEnd":69,"githubUrl":"https://github.com/mikefarah/yq/blob/8b5af0694bb82b41d4ae180fac9972029066f90a/pkg/yqlib/data_tree_navigator.go#L48-L69","documentation":"GetMatchingNodes dispatches an expression node to its registered operator handler (OperationType.Handler). If the handler is nil — the OperationType was never fully registered, or an Operation was constructed with an unknown/custom operation type — yq cannot evaluate it and returns 'unknown operator %v' naming the operation type. This means the expression referenced an operator yq does not know how to execute.","triggerScenarios":"Evaluating an expression whose Operation.OperationType has no Handler, e.g. constructing Operation structs programmatically via the yqlib API with a made-up operationType, or a lexer/operation.go registration mismatch (custom builds where an operator's Handler was left nil).","commonSituations":"Embedding yqlib in Go and building ExpressionNodes by hand instead of through the parser; custom forks or trimmed builds where an operator was registered in the lexer but its Handler is nil; version skew where an expression string uses an operator that does not exist in the installed yq version (usually caught earlier by the lexer, but API users can hit it here).","solutions":["If calling the Go API, only create Operations from the exported OpType variables (e.g. yqlib.CreateStringOpType-style registrations) rather than hand-built operationType structs.","Verify the operator name/expression syntax against your yq version's docs (`yq --help` or operator docs); upgrade yq if the operator was added in a newer release.","If maintaining a fork, ensure every operationType in operation.go sets Handler and that lexer_participle.go does not reference a nil-handler type.","Reproduce with a stock yq binary: if the same expression works there, the issue is in your custom build/integration."],"exampleFix":"// before: hand-rolled operation with no handler\nop := &yqlib.Operation{OperationType: &yqlib.OperationType{Type: \"FROBNICATE\"}}\n// → unknown operator FROBNICATE\n// after: use a registered op type\nop := yqlib.Operation{OperationType: yqlib.StringOpType} // or parse via NewExpressionParser","handlingStrategy":"validation","validationCode":"// Go: build operations only from registered OpTypes\nfunc isRegisteredOp(opType *yqlib.OperationType) bool {\n    return opType != nil && opType.Handler != nil\n}","typeGuard":"if exprNode != nil && exprNode.Operation != nil &&\n    (exprNode.Operation.OperationType == nil || exprNode.Operation.OperationType.Handler == nil) {\n    return fmt.Errorf(\"operator %q has no handler\", exprNode.Operation.OperationType.Type)\n}","tryCatchPattern":"// Go\nout, err := navigator.GetMatchingNodes(ctx, exprNode)\nif err != nil {\n    if strings.HasPrefix(err.Error(), \"unknown operator \") {\n        return fmt.Errorf(\"expression uses unsupported operator; upgrade yq or fix expression: %w\", err)\n    }\n    return err\n}","preventionTips":["Parse expressions through yq's lexer/parser instead of hand-building Operations","Validate expressions against the target yq version in CI before deploying scripts","In forks, enforce that every operationType defines a non-nil Handler"],"tags":["go","yq","expression","operator"],"backgroundTag":"unknown-operator","analyzedSha":"8b5af0694bb82b41d4ae180fac9972029066f90a","analyzedAt":"2026-09-05T10:57:22.766Z","contentChangedAt":"2026-09-05T10:57:22.766Z","schemaVersion":2},"datasetVersion":"2026-09-12T17:17:11.597Z"}