{"record":{"id":"4d0a2e4badcaf27e","repo":"mikefarah/yq","slug":"cannot-match-with-v-can-only-match-strings-hint","errorCode":null,"errorMessage":"cannot match with %v, can only match strings. Hint: Most often you'll want to use '|=' over '=' for this operation","messagePattern":"cannot match with (.+?), can only match strings\\. Hint: Most often you'll want to use '\\|=' over '=' for this operation","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/yqlib/operator_strings.go","lineNumber":442,"sourceCode":"\t\tregExStr = regExNodes.MatchingNodes.Front().Value.(*CandidateNode).Value\n\t}\n\tlog.Debugf(\"regEx %v\", regExStr)\n\tregEx, err := regexp.Compile(regExStr)\n\treturn regEx, matchPrefs, err\n}\n\nfunc matchOperator(d *dataTreeNavigator, context Context, expressionNode *ExpressionNode) (Context, error) {\n\tregEx, matchPrefs, err := extractMatchArguments(d, context, expressionNode)\n\tif err != nil {\n\t\treturn Context{}, err\n\t}\n\n\tvar results = list.New()\n\n\tfor el := context.MatchingNodes.Front(); el != nil; el = el.Next() {\n\t\tnode := el.Value.(*CandidateNode)\n\t\tif node.guessTagFromCustomType() != \"!!str\" {\n\t\t\treturn Context{}, fmt.Errorf(\"cannot match with %v, can only match strings. Hint: Most often you'll want to use '|=' over '=' for this operation\", node.Tag)\n\t\t}\n\n\t\tmatch(matchPrefs, regEx, node, node.Value, results)\n\t}\n\n\treturn context.ChildContext(results), nil\n}\n\nfunc captureOperator(d *dataTreeNavigator, context Context, expressionNode *ExpressionNode) (Context, error) {\n\tregEx, matchPrefs, err := extractMatchArguments(d, context, expressionNode)\n\tif err != nil {\n\t\treturn Context{}, err\n\t}\n\n\tvar results = list.New()\n\n\tfor el := context.MatchingNodes.Front(); el != nil; el = el.Next() {\n\t\tnode := el.Value.(*CandidateNode)","sourceCodeStart":424,"sourceCodeEnd":460,"githubUrl":"https://github.com/mikefarah/yq/blob/8b5af0694bb82b41d4ae180fac9972029066f90a/pkg/yqlib/operator_strings.go#L424-L460","documentation":"match runs a regex against each matched node's value, which requires strings: the guard rejects any node whose resolved tag is not !!str (the tag is printed). As with sub, the hint notes that using plain '=' instead of '|=' is the most common reason the operator receives a non-string node in the first place.","triggerScenarios":"Thrown at pkg/yqlib/operator_strings.go:442 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Use the update-assign form: .a |= match(\"x\") rather than .a = match(\"x\")","Convert with tostring before matching","Confirm the target field is a string and not null/number"],"exampleFix":null,"handlingStrategy":"type-guard","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"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"}