mikefarah/yq · error

system command '%v' failed: %w stderr: %v

Error message

system command '%v' failed: %w
stderr: %v

What it means

The external command launched by the `system` operator exited with a non-zero status, and it wrote something to stderr. The error wraps the underlying exec error (typically *exec.ExitError) and appends the trimmed stderr so the caller can see why the command failed.

Source

Thrown at pkg/yqlib/operator_system.go:130

		var stdin bytes.Buffer
		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. Read the stderr text appended to the error message to diagnose the command's failure
2. Fix the underlying command arguments or input data so the command exits 0
3. If the command uses non-zero exits as signals (e.g. grep), wrap it so it exits 0: `system("sh", "-c", "grep p file || true")` style, or redirect stderr if the noise is benign
4. Check the working directory/environment; the command runs in yq's cwd with the current node piped to stdin

Example fix

// before: grep exits 1 on no match
system("grep"; ["needle", "haystack.txt"])
// after: tolerate no-match
system("sh", "-c", "grep needle haystack.txt || true")

// Go API usage
out, err := yqEval("system(\"tool\")", doc)
if err != nil {
    var exitErr *exec.ExitError
    if strings.Contains(err.Error(), "failed:") && strings.Contains(err.Error(), "stderr:") {
        // parse stderr portion after "stderr:" for the command's diagnostics
    } else if errors.As(err, exitErr) { /* exit code at exitErr.ExitCode() */ }
}

When it happens

Trigger: `system("grep"; ["pattern"])` where grep finds nothing (exit 1) and prints to stderr, or any command that fails — bad flags, missing files, permission errors — while emitting stderr output.

Common situations: Commands assuming a working directory or environment that differs in the yq run, tools like ssh/git/curl writing warnings to stderr on non-fatal errors, or legitimately failing commands (grep no-match, test false) whose non-zero exit codes yq treats as failures.

Related errors

• system command '%v' failed: %w
• 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/48bd4c312437b575. Report an issue: GitHub.