{"record":{"id":"cc517fe652c77032","repo":"google-gemini/gemini-cli","slug":"command-cmd-str-failed-with-exit-code-returnc","errorCode":null,"errorMessage":"Command '{cmd_str}' failed with exit code {returncode}","messagePattern":"Command '(.+?)' failed with exit code (.+?)","errorType":"exception","errorClass":"CommandExecutionError","httpStatus":null,"severity":"error","filePath":"tools/caretaker-agent/cloudrun/pr-generator/workflow/command_executor.py","lineNumber":140,"sourceCode":"                text=True,\n                timeout=timeout,\n                check=False,\n            )\n\n            stdout_str = result.stdout.strip() if result.stdout else \"\"\n            stderr_str = result.stderr.strip() if result.stderr else \"\"\n\n            if result.returncode != 0:\n                logging.error(\n                    \"Command execution failed: %s (Exit Code: %s)\",\n                    cmd_str,\n                    result.returncode,\n                )\n                if stdout_str:\n                    logging.error(\"Stdout:\\n%s\", stdout_str)\n                if stderr_str:\n                    logging.error(\"Stderr:\\n%s\", stderr_str)\n                raise CommandExecutionError(\n                    cmd=args,\n                    returncode=result.returncode,\n                    stdout=stdout_str,\n                    stderr=stderr_str,\n                )\n\n            return stdout_str\n        except Exception as e:\n            if not isinstance(e, CommandExecutionError):\n                logging.exception(\n                    \"An unexpected error occurred during command execution: %s\",\n                    cmd_str,\n                )\n            raise\n","sourceCodeStart":122,"sourceCodeEnd":155,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/tools/caretaker-agent/cloudrun/pr-generator/workflow/command_executor.py#L122-L155","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Inspect e.stderr and e.returncode first — the underlying tool already told you why it failed.","Re-run the failing command manually in the same cwd/env to reproduce.","Forward required env (GH_TOKEN, PATH, etc.) via the env= argument.","If the failure is intermittent (network/git lock), retry with backoff."],"exampleFix":"# before\nout = CommandExecutor.run(['git', 'merge', base])\n# after\ntry: out = CommandExecutor.run(['git', 'merge', base])\nexcept CommandExecutionError as e:\n    logger.error('merge failed: %s', e.stderr); raise","handlingStrategy":"try-catch","validationCode":"# dry-run validate args/env before executing\nimport shutil\nif not shutil.which(args[0]): raise ValueError(f'binary not on PATH: {args[0]}')","typeGuard":"def is_command_execution_error(e: Exception) -> bool:\n    return isinstance(e, CommandExecutionError)","tryCatchPattern":"try:\n    out = CommandExecutor.run(cmd, cwd=cwd, env=env)\nexcept CommandExecutionError as e:\n    log.error('stderr=%s rc=%s', e.stderr, e.returncode)\n    raise","preventionTips":["Forward required env (PATH, tokens) explicitly via env=.","Log e.stderr — it usually contains the actionable cause."],"tags":["subprocess","command-execution","shell","python"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}