Error Handling Reference
Deployment Failures
google.api_core.exceptions.NotFound: 404 Reasoning engine not found
- Cause: The reasoning engine resource name is incorrect or the resource was deleted.
- Fix: Verify the resource name with
client.agent_engines.list()and confirm the project/location match.
google.api_core.exceptions.PermissionDenied: 403 Permission denied on resource
- Cause: The service account or user lacks required IAM roles.
- Fix: Grant
roles/aiplatform.userfor querying agents,roles/aiplatform.adminfor creating/deleting. Usegcloud projects get-iam-policy PROJECT_IDto audit current bindings.
google.api_core.exceptions.InvalidArgument: 400 Invalid agent configuration
- Cause: The agent definition has invalid fields, unsupported model, or malformed tools.
- Fix: Verify the model string (e.g.,
gemini-2.5-flash), ensure all tool functions have proper type hints and docstrings, and check thatrequirementslist includes all needed packages.
google.api_core.exceptions.ResourceExhausted: 429 Quota exceeded
- Cause: Project has hit the Agent Engine quota (default: 10 reasoning engines per project).
- Fix: Request quota increase via Cloud Console > IAM & Admin > Quotas, or delete unused agents with
client.agent_engines.delete(name=resource_name).
Deployment hangs or times out
- Cause: Large dependency list, network issues, or package build failures in the remote environment.
- Fix: Minimize
requirementsto only what the agent needs. Pin exact versions. Check Cloud Build logs viagcloud builds list --project=PROJECT_ID.
Authentication & Authorization Issues
google.auth.exceptions.DefaultCredentialsError: Could not automatically determine credentials
- Cause: No Application Default Credentials configured.
- Fix: Run
gcloud auth application-default loginfor local development, or setGOOGLE_APPLICATION_CREDENTIALSto a service account key path. For production, use Workload Identity Federation.
google.auth.exceptions.RefreshError: ('invalid_grant: Token has been expired or revoked')
- Cause: Cached credentials are stale or the service account key was rotated.
- Fix: Re-authenticate with
gcloud auth application-default login. For service accounts, generate a new key and updateGOOGLE_APPLICATION_CREDENTIALS.
Agent runs but returns permission errors at runtime
- Cause: The Agent Engine service agent (the identity the deployed agent runs as) lacks permissions to call downstream APIs (e.g., GKE, Cloud Run).
- Fix: Grant the Agent Engine service agent (
service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com) the required roles for the APIs the agent's tools invoke.
Orchestration Failures
Sub-agent in SequentialAgent fails mid-pipeline
- Cause: One agent in the chain returned an error or produced output the next agent could not process.
- Fix: Wrap each sub-agent in error-handling instructions. Add a
try/exceptaround the orchestrator call. Check which sub-agent failed by inspecting theeventsin the runner response.
ParallelAgent produces inconsistent results
- Cause: Parallel sub-agents share no state by default; if they depend on each other's output, results are non-deterministic.
- Fix: Use
SequentialAgentwhen ordering matters. Only useParallelAgentfor truly independent tasks.
LoopAgent exceeds max iterations
- Cause: The exit condition was never met, or the loop agent's
should_continuelogic has a bug. - Fix: Set
max_iterationson theLoopAgent. Add explicit exit conditions in the agent's instructions. Monitor iteration count in logs.
SDK & Import Errors
ImportError: cannot import name 'Agent' from 'google.adk'
- Cause: Using the wrong import path.
- Fix: The correct import is
from google.adk.agents import Agent. Other common imports:from google.adk.agents import SequentialAgent, ParallelAgent, LoopAgentfrom google.adk.runners import Runnerfrom google.adk.sessions import VertexAiSessionServicefrom google.adk.tools import FunctionTool
ModuleNotFoundError: No module named 'google.adk'
- Cause: ADK SDK not installed or wrong Python environment.
- Fix: Install with
pip install google-adk>=1.15.1. Verify withpython -c "import google.adk; print(google.adk.__version__)".
Agent Engine Management (No gcloud CLI)
There is no gcloud ai agents or gcloud alpha ai agent-engines CLI. All Agent Engine management is done via the Python SDK:
import vertexai
client = vertexai.Client(project="PROJECT_ID", location="us-central1")
# List agents
agents = client.agent_engines.list()
# Get a specific agent
agent = client.agent_engines.get(
name="projects/PROJECT/locations/LOC/reasoningEngines/ID"
)
# Create/deploy an agent
remote = client.agent_engines.create(agent_engine=my_agent, requirements=[...])
# Delete an agent
client.agent_engines.delete(name=agent.resource_name)A2A Protocol Errors
AgentCard not found at /.well-known/agent-card
- Cause: The agent does not expose an A2A-compliant AgentCard, or the URL is wrong.
- Fix: Verify the agent was deployed with A2A support. The AgentCard endpoint is
/.well-known/agent-card(note: no trailing slash). Ensure the agent framework generates this endpoint.
tasks/send returns 405 Method Not Allowed
- Cause: The agent endpoint does not support the A2A task submission method.
- Fix: Confirm the agent was built with A2A protocol support (
a2a-sdk). Check that the server handles POST to/tasks/sendwith JSON-RPC 2.0 format.
Task polling returns stale status
- Cause: Eventual consistency or caching in the agent's task store.
- Fix: Implement exponential backoff in polling (start at 2s, max 30s). Use the task's
updatedAttimestamp to detect stale responses.