{"record":{"id":"9b51e92229fb9993","repo":"mikefarah/yq","slug":"system-operator-command-must-be-a-string-scalar","errorCode":null,"errorMessage":"system operator: command must be a string scalar","messagePattern":"system operator: command must be a string scalar","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/yqlib/operator_system.go","lineNumber":53,"sourceCode":"\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}\n\treturn cmdNode.Value, nil\n}\n\nfunc systemOperator(d *dataTreeNavigator, context Context, expressionNode *ExpressionNode) (Context, error) {\n\tif !ConfiguredSecurityPreferences.EnableSystemOps {\n\t\treturn Context{}, fmt.Errorf(\"system operations are disabled, use --security-enable-system-operator to enable\")\n\t}\n\n\t// determine at parse time whether we have (command; args) or just (command)\n\thasArgs := expressionNode.RHS.Operation.OperationType == blockOpType\n\n\tvar results = list.New()\n\n\tfor el := context.MatchingNodes.Front(); el != nil; el = el.Next() {","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/mikefarah/yq/blob/8b5af0694bb82b41d4ae180fac9972029066f90a/pkg/yqlib/operator_system.go#L35-L71","documentation":"The `system` operator's resolved command must be a string scalar. resolveCommandNode throws this when the first node returned by the command expression is not a scalar, or is a scalar whose (effective) tag is not !!str — e.g. a number, boolean, map, or sequence.","triggerScenarios":"`system(.port)` where .port is `!!int`, `system(.enabled)` where the value is `!!bool`, or `system(.config)` where .config is a map. Also custom-typed scalars whose tag does not resolve to !!str.","commonSituations":"Pointing the command expression at a numeric/boolean field by mistake, or reading a command from data loaded where the tag is a custom type rather than a plain string.","solutions":["Point the command expression at a string field, e.g. `system(.commandString)`","Coerce non-string scalars to a string: `system(.port | tostring)`","Check the document tags with `yq 'path | tag'` to confirm the node is !!str"],"exampleFix":"// before: .port is !!int\nsystem(.port)\n// after: convert to string scalar\nsystem(.port | tostring)","handlingStrategy":"type-guard","validationCode":"// only pass string scalars as the command\nsystem(select(tag == \"!!str\") | .cmd)","typeGuard":"// guard in expression form\ndef isStrScalar: tag == \"!!str\";\n.cmd | select(isStrScalar) | system(.)","tryCatchPattern":"// Go API usage\nif err != nil && strings.Contains(err.Error(), \"command must be a string scalar\") {\n    // coerce or report: the selected node was not !!str\n}","preventionTips":["Check the node tag with yq '<expr> | tag' before using it as a command","Coerce numbers/booleans with tostring() when they should be commands","Avoid pointing the command expression at maps or sequences"],"tags":["yq","system-operator","type-error","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"}