google-gemini/gemini-cli · error · CommandExecutionError

Command '{cmd_str}' failed with exit code {returncode}

Error message

Command '{cmd_str}' failed with exit code {returncode}

What it means

CommandExecutionError 'Command \'X\' failed with exit code N' is raised by CommandExecutor.run after subprocess.run returns a non-zero exit code. The exception carries .cmd, .returncode, .stdout, .stderr for diagnostics. Only non-zero exits raise; spawn/timeout failures fall through to the generic except branch.

Source

Thrown at tools/caretaker-agent/cloudrun/pr-generator/workflow/command_executor.py:140

                text=True,
                timeout=timeout,
                check=False,
            )

            stdout_str = result.stdout.strip() if result.stdout else ""
            stderr_str = result.stderr.strip() if result.stderr else ""

            if result.returncode != 0:
                logging.error(
                    "Command execution failed: %s (Exit Code: %s)",
                    cmd_str,
                    result.returncode,
                )
                if stdout_str:
                    logging.error("Stdout:\n%s", stdout_str)
                if stderr_str:
                    logging.error("Stderr:\n%s", stderr_str)
                raise CommandExecutionError(
                    cmd=args,
                    returncode=result.returncode,
                    stdout=stdout_str,
                    stderr=stderr_str,
                )

            return stdout_str
        except Exception as e:
            if not isinstance(e, CommandExecutionError):
                logging.exception(
                    "An unexpected error occurred during command execution: %s",
                    cmd_str,
                )
            raise

View on GitHub (pinned to 5024443c72)

Solutions

1. Inspect e.stderr and e.returncode first — the underlying tool already told you why it failed.
2. Re-run the failing command manually in the same cwd/env to reproduce.
3. Forward required env (GH_TOKEN, PATH, etc.) via the env= argument.
4. If the failure is intermittent (network/git lock), retry with backoff.

Example fix

# before
out = CommandExecutor.run(['git', 'merge', base])
# after
try: out = CommandExecutor.run(['git', 'merge', base])
except CommandExecutionError as e:
    logger.error('merge failed: %s', e.stderr); raise

# dry-run validate args/env before executing
import shutil
if not shutil.which(args[0]): raise ValueError(f'binary not on PATH: {args[0]}')

def is_command_execution_error(e: Exception) -> bool:
    return isinstance(e, CommandExecutionError)

try:
    out = CommandExecutor.run(cmd, cwd=cwd, env=env)
except CommandExecutionError as e:
    log.error('stderr=%s rc=%s', e.stderr, e.returncode)
    raise

When it happens

Trigger: CommandExecutor.run(cmd, cwd, env, timeout) -> subprocess.run(check=False) -> result.returncode != 0 -> logs stdout/stderr at ERROR -> raise CommandExecutionError(cmd=args, returncode, stdout, stderr).

Common situations: git/gh/npm step failing in the PR-generation workflow (e.g. merge conflict, auth, missing binary); wrong cwd; env var (like GH_TOKEN) not forwarded; command exceeds timeout and exits non-zero.

Related errors

• Triage execution failed: {raw_output}
• Exiting due to a confirmation prompt requested by the comman
• Invalid syntax${contextInfo}: Unclosed injection starting at
• Security configuration not loaded. Cannot verify shell comma
• ${this.commandName} cannot be run. Blocked command: "${comma

AI-assisted analysis of google-gemini/gemini-cli@5024443c72 (2026-08-12). Data as JSON: /api/errors/cc517fe652c77032. Report an issue: GitHub.