mikefarah/yq · error

system command '%v' failed: %w

Error message

system command '%v' failed: %w

What it means

The external command launched by the `system` operator exited with a non-zero status and produced no stderr output, so only the wrapped exec error is reported. This distinguishes failures like 'executable not found' (exec.ErrNotFound / exec.Error) or silent non-zero exits from failures that printed diagnostics.

Source

Thrown at pkg/yqlib/operator_system.go:132

		encoded, err := encodeToYamlString(candidate)
		if err != nil {
			return Context{}, err
		}
		stdin.WriteString(encoded)

		// #nosec G204 - intentional: user must explicitly enable this operator
		cmd := exec.Command(command, args...)
		cmd.Stdin = &stdin
		var stderr bytes.Buffer
		cmd.Stderr = &stderr

		output, err := cmd.Output()
		if err != nil {
			stderrStr := strings.TrimSpace(stderr.String())
			if stderrStr != "" {
				return Context{}, fmt.Errorf("system command '%v' failed: %w\nstderr: %v", command, err, stderrStr)
			}
			return Context{}, fmt.Errorf("system command '%v' failed: %w", command, err)
		}

		result := string(output)
		if strings.HasSuffix(result, "\r\n") {
			result = result[:len(result)-2]
		} else if strings.HasSuffix(result, "\n") {
			result = result[:len(result)-1]
		}
		newNode := candidate.CreateReplacement(ScalarNode, "!!str", result)
		results.PushBack(newNode)
	}

	return context.ChildContext(results), nil
}

View on GitHub (pinned to 8b5af0694b)

Solutions

1. Verify the executable exists on PATH in the environment yq runs in (which <cmd>); install it or use an absolute path: system("/usr/bin/tool")
2. If the failure is silent, run the command manually to see its exit code and output
3. Wrap the command with sh -c to capture/normalize exit status if non-zero exits are expected
4. Check permissions on the binary (executable bit)

Example fix

// before: relies on PATH
system("kubectl"; ["version"])
// after: absolute path when PATH differs
system("/usr/local/bin/kubectl"; ["version"])

// Go API usage
if err != nil && strings.Contains(err.Error(), "executable file not found") {
    // tool missing from PATH: install it or switch to an absolute path
}

When it happens

Trigger: `system("nonexistent-tool")` where the binary is not on PATH (exec: "nonexistent-tool": executable file not found in $PATH), or a command that fails silently with a non-zero exit code and empty stderr.

Common situations: Running yq in a container/CI image that lacks the tool installed locally, PATH differences between shell and yq's environment, or tools that signal failure only via exit codes.

Related errors

• system command '%v' failed: %w stderr: %v
• system operator: argument must be a non-null scalar; got kin
• system operator: args must be a non-null scalar or sequence
• system operator: command expression returned no results
• system operator: command must be a string scalar

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