{"record":{"id":"952164798eb49399","repo":"mikefarah/yq","slug":"system-operator-args-must-be-a-non-null-scalar-or","errorCode":null,"errorMessage":"system operator: args must be a non-null scalar or sequence of non-null scalars; got kind=%v tag=%v","messagePattern":"system operator: args must be a non-null scalar or sequence of non-null scalars; got kind=(.+?) tag=(.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/yqlib/operator_system.go","lineNumber":39,"sourceCode":"\t\t\t\tcontinue\n\t\t\t}\n\t\t\tif child.Kind != ScalarNode || child.Tag == \"!!null\" {\n\t\t\t\treturn nil, fmt.Errorf(\"system operator: argument must be a non-null scalar; got kind=%v tag=%v\", child.Kind, child.Tag)\n\t\t\t}\n\t\t\targs = append(args, child.Value)\n\t\t}\n\t\tif len(args) == 0 {\n\t\t\treturn nil, nil\n\t\t}\n\t\treturn args, nil\n\t}\n\n\t// Single-argument case: only accept a non-null scalar node.\n\tif argsNode.Tag == \"!!null\" {\n\t\treturn nil, nil\n\t}\n\tif argsNode.Kind != ScalarNode {\n\t\treturn nil, fmt.Errorf(\"system operator: args must be a non-null scalar or sequence of non-null scalars; got kind=%v tag=%v\", argsNode.Kind, argsNode.Tag)\n\t}\n\treturn []string{argsNode.Value}, nil\n}\n\nfunc resolveCommandNode(commandNodes Context) (string, error) {\n\tif commandNodes.MatchingNodes.Front() == nil {\n\t\treturn \"\", fmt.Errorf(\"system operator: command expression returned no results\")\n\t}\n\tif commandNodes.MatchingNodes.Len() > 1 {\n\t\tlog.Debugf(\"system operator: command expression returned %d results, using first\", commandNodes.MatchingNodes.Len())\n\t}\n\tcmdNode := commandNodes.MatchingNodes.Front().Value.(*CandidateNode)\n\tif cmdNode.Kind != ScalarNode || cmdNode.guessTagFromCustomType() != \"!!str\" {\n\t\treturn \"\", fmt.Errorf(\"system operator: command must be a string scalar\")\n\t}\n\tif cmdNode.Value == \"\" {\n\t\treturn \"\", fmt.Errorf(\"system operator: command must be a non-empty string\")\n\t}","sourceCodeStart":21,"sourceCodeEnd":57,"githubUrl":"https://github.com/mikefarah/yq/blob/8b5af0694bb82b41d4ae180fac9972029066f90a/pkg/yqlib/operator_system.go#L21-L57","documentation":"The yq `system` operator's args expression must yield either a single non-null scalar or a sequence of non-null scalars. resolveSystemArgs throws this when the single args node is a map or sequence-of-sequences (anything that is not a ScalarNode). A null args node is tolerated (treated as no args), but other non-scalars are rejected.","triggerScenarios":"Calling `system(\"cmd\"; .config)` where `.config` is a map, or `system(\"cmd\"; .list[0].nested)` where the resolved node is a mapping, so the args node has kind MapNode or SequenceNode at the top level.","commonSituations":"Pointing the args expression at a YAML object by mistake, expecting it to be spread into arguments, or forgetting an array index so a whole sequence-of-objects is resolved instead of a scalar.","solutions":["Point the args expression at a scalar, e.g. `system(\"cmd\"; .name)` instead of `system(\"cmd\"; .)`","If the args are in a map, extract the fields you need into a flat sequence: `system(\"cmd\"; [.config.host, .config.port])`","Coerce values to strings with tostring() if they are complex and you want their text form"],"exampleFix":"// before: passing a whole map as args\nsystem(\"curl\"; .request)\n// after: pass a flat sequence of scalars\nsystem(\"curl\"; [.request.url, .request.method])","handlingStrategy":"validation","validationCode":"// ensure args node is scalar or flat sequence of scalars\nsystem(\"curl\"; (if (.args | tag) == \"!!seq\" then [.args[] | tostring] else [.args | tostring] end))","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Point the args expression at a scalar or a flat array, never a map","Extract needed fields from objects into a flat sequence before passing","Test the args expression alone (yq '<args-expr>' file) to see the resolved node type"],"tags":["yq","system-operator","argument-validation","yaml"],"backgroundTag":"invalid-operator-argument","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"}