{"record":{"id":"77112cef2d796aeb","repo":"mikefarah/yq","slug":"system-operator-argument-must-be-a-non-null-scala","errorCode":null,"errorMessage":"system operator: argument must be a non-null scalar; got kind=%v tag=%v","messagePattern":"system operator: argument must be a non-null scalar; got kind=(.+?) tag=(.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/yqlib/operator_system.go","lineNumber":24,"sourceCode":"\t\"fmt\"\n\t\"os/exec\"\n\t\"strings\"\n)\n\nfunc resolveSystemArgs(argsNode *CandidateNode) ([]string, error) {\n\tif argsNode == nil {\n\t\treturn nil, nil\n\t}\n\n\tif argsNode.Kind == SequenceNode {\n\t\targs := make([]string, 0, len(argsNode.Content))\n\t\tfor _, child := range argsNode.Content {\n\t\t\t// Only non-null scalar children are valid arguments.\n\t\t\tif child == nil {\n\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}","sourceCodeStart":6,"sourceCodeEnd":42,"githubUrl":"https://github.com/mikefarah/yq/blob/8b5af0694bb82b41d4ae180fac9972029066f90a/pkg/yqlib/operator_system.go#L6-L42","documentation":"The yq `system` operator runs an external command; its arguments must each be a plain, non-null scalar. This error is thrown by resolveSystemArgs when an element of the args sequence is a map, sequence, or a null scalar. It aborts evaluation before any command is executed.","triggerScenarios":"Using `system(\"cmd\"; $args)` where the args expression resolves to a sequence containing a nested sequence or map (e.g. an array of arrays), or an explicit null item like `system(\"echo\"; [\"a\", null, \"b\"])`.","commonSituations":"Building argument arrays programmatically with entries defaulted to null (e.g. from optional config keys or `.x // null`), or accidentally passing a nested structure because the args path matched the wrong node.","solutions":["Inspect the args sequence and remove or filter null/nested entries before passing to system, e.g. `[.[] | select(. != null)]`","Ensure each argument is a string/int/bool scalar: quote values in the source YAML if they were being parsed as maps or sequences","Dynamically build args with map(...) to coerce each element to a scalar string"],"exampleFix":"// before: args contains a null entry\nsystem(\"echo\"; [.a, .b])   # .b is null -> error\n// after: filter nulls first\nsystem(\"echo\"; [.a, .b] | map(select(. != null)))","handlingStrategy":"validation","validationCode":"// validate args sequence before system()\ndef cleanArgs: map(select(tag != \"!!null\" and (tag == \"!!str\" or tag == \"!!int\" or tag == \"!!float\" or tag == \"!!bool\")));\nsystem(\"echo\"; ([.a, .b] | cleanArgs))","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Filter null entries out of argument sequences with map(select(. != null))","Ensure each argument element is a plain scalar; flatten nested arrays before passing","Quote scalar values in source YAML so they do not parse as maps/sequences"],"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"}