What causes "Agent '{role}' execution failed: {e}" in google-gemini/gemini-cli?

Read the chained `__cause__` (the original Exception) — the wrapped message is the real diagnosis.

google-gemini/gemini-cli · error · AgentRunnerError

Agent '{role}' execution failed: {e}

Error message

Agent '{role}' execution failed: {e}

What it means

AgentRunnerError 'Agent \'X\' execution failed: e' wraps ANY exception raised inside the agent conversation loop (after `if Agent is None` has passed). The original exception is chained via `from e`, and an 'unexpected error' log line is emitted. The message tells you which role failed and the underlying error text.

Source

Thrown at tools/caretaker-agent/cloudrun/pr-generator/workflow/agent_runner.py:251

                        # Accumulate outputs
                        for step_idx in sorted(step_contents.keys()):
                            stdout_list.append(step_contents[step_idx])

                        for step_idx in sorted(step_thoughts.keys()):
                            thinking_list.append(step_thoughts[step_idx])

            full_output = "\n".join(stdout_list)
            if thinking_list:
                joined_thoughts = "\n".join(thinking_list)
                full_output += f"\nThoughts:\n{joined_thoughts}"

            logging.info("Agent '%s' execution completed successfully.", role)
            return full_output

        except Exception as e:
            logging.exception("Failed to execute agent loop for role: %s", role)
            raise AgentRunnerError(f"Agent '{role}' execution failed: {e}") from e

View on GitHub (pinned to 5024443c72)

Solutions

Read the chained `__cause__` (the original Exception) — the wrapped message is the real diagnosis.
Verify Vertex config: project_id, location, model_name are valid and the SA has aiplatform permissions.
Check AgentRunner logs: logging.exception('Failed to execute agent loop for role: %s') prints the full traceback.
Retry on transient errors (rate limits); fix config on persistent ones.

Example fix

# before
except Exception as e: raise AgentRunnerError(...) from e  # original swallowed
# after
except Exception as e:
    logging.exception('underlying cause')
    raise AgentRunnerError(...) from e  # inspect e.__cause__ in caller

Defensive patterns

Strategy: try-catch

Validate before calling

# pre-flight: auth + region
from google.cloud import aiplatform
aiplatform.init(project=runner.project_id, location=runner.location)

Type guard

def is_agent_execution_error(e: Exception) -> bool:
    return isinstance(e, AgentRunnerError) and 'execution failed' in str(e)

Try / catch

try:
    out = runner.run(role, prompt, repo_path)
except AgentRunnerError as e:
    log.error('underlying: %r', e.__cause__)
    raise

Prevention

Always log e.__cause__ — the wrapped error is the real signal.
Validate Vertex project/location/model before entering the agent loop.

When it happens

Trigger: Inside run()'s try block: LocalAgentConfig build, `async with Agent(config)`, `agent.conversation.send(prompt)`, or `receive_steps()` raises -> except Exception as e -> raise AgentRunnerError(f"Agent '{role}' execution failed: {e}") from e.

Common situations: Vertex AI auth/permission errors; project_id or location misconfigured; model_name invalid or unavailable in the region; the Antigravity SDK raised on a malformed step; rate limit / quota during receive_steps.

Related errors

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