system operator: command expression returned no results

Error message

system operator: command expression returned no results

What it means

The `system` operator requires a command string from its RHS expression, but the expression matched zero nodes. resolveCommandNode throws this when the command expression yields an empty result set, so there is nothing to execute.

Source

Thrown at pkg/yqlib/operator_system.go:46

		if len(args) == 0 {
			return nil, nil
		}
		return args, nil
	}

	// Single-argument case: only accept a non-null scalar node.
	if argsNode.Tag == "!!null" {
		return nil, nil
	}
	if argsNode.Kind != ScalarNode {
		return 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)
	}
	return []string{argsNode.Value}, nil
}

func resolveCommandNode(commandNodes Context) (string, error) {
	if commandNodes.MatchingNodes.Front() == nil {
		return "", fmt.Errorf("system operator: command expression returned no results")
	}
	if commandNodes.MatchingNodes.Len() > 1 {
		log.Debugf("system operator: command expression returned %d results, using first", commandNodes.MatchingNodes.Len())
	}
	cmdNode := commandNodes.MatchingNodes.Front().Value.(*CandidateNode)
	if cmdNode.Kind != ScalarNode || cmdNode.guessTagFromCustomType() != "!!str" {
		return "", fmt.Errorf("system operator: command must be a string scalar")
	}
	if cmdNode.Value == "" {
		return "", fmt.Errorf("system operator: command must be a non-empty string")
	}
	return cmdNode.Value, nil
}

func systemOperator(d *dataTreeNavigator, context Context, expressionNode *ExpressionNode) (Context, error) {
	if !ConfiguredSecurityPreferences.EnableSystemOps {
		return Context{}, fmt.Errorf("system operations are disabled, use --security-enable-system-operator to enable")
	}

View on GitHub (pinned to 8b5af0694b)

Solutions

Verify the field name in the command expression exists in the input documents
Provide a fallback default: `system(.cmd // "echo")` or use alternative// to supply a literal
Check the input data — run just the command expression alone (e.g. `yq '.cmd' file.yml`) to confirm it returns a value

Example fix

// before: .cmd may be missing
system(.cmd)
// after: default when missing
system(.cmd // "echo")

Defensive patterns

Strategy: fallback

Validate before calling

// default the command expression
system(.cmd // "echo")

Try / catch

// Go API usage
result, err := yqEval(expr, doc)
if err != nil && strings.Contains(err.Error(), "command expression returned no results") {
    // handle missing command field: use default or skip
}

Prevention

Supply a default with // in the command expression
Verify the field exists in all input documents before piping into system()
Run the command expression standalone to confirm it matches nodes

When it happens

Trigger: `system(.missingCommandField)` where the key does not exist on the current node (e.g. `.cmd` absent from the YAML), or a command expression filtered to nothing like `system(.cmds[] | select(.enabled))` matching no entries.

Common situations: Typo in the field name holding the command, running the expression against documents that lack the command key, or a select() filter that eliminates all candidates.

Related errors

AI-assisted analysis of mikefarah/yq@8b5af0694b (2026-09-05). Data as JSON: /api/errors/9ac15d9f69a2d9a0. Report an issue: GitHub.