This page is the starting point for troubleshooting Gemini Enterprise Agent Platform. Use it to
[diagnose an error](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting.md.txt#diagnose), [look up a specific error](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting.md.txt#error-catalog),
[find the guide for your task](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting.md.txt#guides), or [get
support](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting#get-support).

## Diagnose an error

Before you look for a specific fix, collect the following information:

### Read the error

Note the status code, such as `400` or `429`, and the exact message text. You
can look up both in the [error catalog](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting.md.txt#error-catalog).

You can also identify the specific failure from a machine-readable reason,
documentation link, or prefiltered log view if those are present in the error
message.

### Find the logs

To search and filter agent error logs, [use the Logs Explorer](https://docs.cloud.google.com/logging/docs/view/logs-explorer-interface.md.txt), set
**Resource type** to **Vertex AI Reasoning Engine** , and select the
corresponding **Resource container** value (your project number) and
**Reasoning engine ID** value.

### Check quotas and service health

Errors that appear intermittently, or that started without a change on your
side, are often caused by quota or by an ongoing incident:

- Compare your usage against [Quotas and system
  limits](https://docs.cloud.google.com/gemini-enterprise-agent-platform/resources/agent-quotas).
- Check [Google Cloud Service Health](https://status.cloud.google.com/) for an ongoing incident in your region.

## Error catalog

Find the error you received in the following table. Errors with a status code
are listed first, in numerical order, followed by the rest in alphabetical
order. If your error isn't listed, use the [troubleshooting guides](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting.md.txt#guides)
for the task you were trying to complete.

| Status code or message | Resolution |
|---|---|
| `400`, `FAILED_PRECONDITION`, `REASONING_ENGINE_A2A_NOT_CONFIGURED` | [A2A methods not defined](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-usage.md.txt#a2a-not-configured) |
| `400`, `FAILED_PRECONDITION`, `REASONING_ENGINE_NO_RUNNING_INSTANCES` | [Agent has no running instances](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-usage.md.txt#no-running-instances) |
| `400`, `INVALID_ARGUMENT`, `REASONING_ENGINE_BUILD_FAILED` | [Container image build failed](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-deployment.md.txt#build-failed) |
| `400`, `INVALID_ARGUMENT`, `REASONING_ENGINE_CONTAINER_FAILED_TO_START` | [Container failed to start](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-deployment.md.txt#container-failed-to-start) |
| `400`, `INVALID_ARGUMENT`, `REASONING_ENGINE_SECRET_ACCESS_DENIED`, `referenced by spec.deployment_spec.secret_env` | [Secret Manager access errors](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-deployment.md.txt#secret-access-errors) |
| `InvalidArgument: 400 Provided filter is not valid` | [Error when filtering the list of agents](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/managing-deployed-agents.md.txt#filter-agents-errors) |
| `401` `Context-Aware Access requirements are not met`, `401` `Request had invalid authentication credentials` | [401 authorization errors](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/runtime-setup.md.txt#401-errors) |
| `403 Forbidden` on an outbound request | [403 Forbidden errors](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/troubleshoot-agent-gateway.md.txt#confirm-egress-error) |
| `403`, `PERMISSION_DENIED`, `REASONING_ENGINE_NOT_ACTIVE` | [Agent isn't active](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-usage.md.txt#agent-not-active) |
| `404`, `NOT_FOUND`, `REASONING_ENGINE_NOT_FOUND` | [Agent not found](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-usage.md.txt#agent-not-found) |
| `NotFound: 404 Can not copy from "gs://..."` | [Cloud Storage bucket subdirectory isn't created](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-deployment.md.txt#storage-bucket-subdirectory-errors) |
| `409`, `ABORTED`, `REASONING_ENGINE_AGENT_GATEWAY_CONCURRENT_PROVISION_ABORTED` | [Agent Gateway binding aborted](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-deployment.md.txt#agent-gateway-concurrent-provision-aborted) |
| `429`, `RESOURCE_EXHAUSTED` | [API rate limit or quota exceeded](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-deployment.md.txt#error-429) |
| `429`, `RESOURCE_EXHAUSTED`, `at capacity` | [Region temporarily at capacity](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-deployment.md.txt#region-capacity) |
| `429`, `RESOURCE_EXHAUSTED`, `max_instances` | [Maximum instances exceed regional limit](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-deployment.md.txt#max-instances-limit) |
| `429`, `RESOURCE_EXHAUSTED`, `REASONING_ENGINE_AGENT_GATEWAY_LOOKUP_THROTTLED` | [Agent Gateway lookup throttled](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-deployment.md.txt#agent-gateway-lookup-throttled) |
| `500` internal server error from a prebuilt template | [Prebuilt template errors](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-deployment.md.txt#prebuilt-template-errors) |
| `500`, `INTERNAL`, `REASONING_ENGINE_PROVISIONING_FAILED` | [Environment provisioning failed](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-deployment.md.txt#provisioning-failed) |
| `503`, `UNAVAILABLE`, `REASONING_ENGINE_AGENT_GATEWAY_PROVISION_UNAVAILABLE` | [Agent Gateway binding temporarily unavailable](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-deployment.md.txt#agent-gateway-provision-unavailable) |
| `504`, `DEADLINE_EXCEEDED`, `REASONING_ENGINE_AGENT_GATEWAY_PROVISION_TIMEOUT` | [Agent Gateway binding timed out](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-deployment.md.txt#agent-gateway-provision-timeout) |
| `504`, `DEADLINE_EXCEEDED`, `REASONING_ENGINE_BUILD_TIMEOUT` | [Container image build timed out](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-deployment.md.txt#build-timeout) |
| `504`, `DEADLINE_EXCEEDED`, `REASONING_ENGINE_CONTAINER_START_TIMEOUT` | [Container didn't start in time](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-deployment.md.txt#container-start-timeout) |
| Certificate verification failures reaching a self-signed or private CA destination | [Self-signed or private CA destinations fail to connect](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/troubleshoot-agent-gateway.md.txt#self-signed-ca-fail) |
| `cloudpickle` or `pydantic` version conflicts when serializing your agent | [Serialization errors](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-deployment.md.txt#serialization-errors) |
| Code execution times out, file I/O failures in a sandbox | [Code execution issues](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/code-execution.md.txt#code-execution-issues) |
| Empty list from `.operation_schemas()` | [Operation schemas is empty](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-usage.md.txt#operation-schemas-empty) |
| `failed to start and cannot serve traffic` or `Request is prohibited by organization's policy`, inside a VPC Service Controls perimeter | [VPC-SC violation errors](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-deployment.md.txt#vpc-sc-violation-errors) |
| `failed to start and cannot serve traffic`, on your first custom container (BYOC) deployment in a region | [BYOC first-time creation error](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-creation.md.txt#byoc-first-creation-error) |
| `google.api_core.exceptions.Unknown: None`, `Failed to convert project number to project ID`, during startup | [Errors during Agent Runtime startup](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/troubleshoot-agent-gateway.md.txt#bootstrap-errors) |
| `iam.serviceAccounts.actAs` denied, metadata server unavailable | [Custom service account errors](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-deployment.md.txt#custom-service-account-errors) |
| `ImportError: cannot import name 'reasoning_engines'`, `ImportError: cannot import name 'agent_engines'` | [Outdated version of the Agent Platform SDK for Python](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/runtime-setup.md.txt#outdated-vertex-sdk-errors) |
| `PermissionDenied` when you query an agent | [`PermissionDenied` error when querying your agent](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-usage.md.txt#permission-denied) |
| `Reasoning Engine Execution failed` | [Reasoning Engine Execution failed](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-usage.md.txt#execution-failed) |
| `RuntimeError: Failed to generate memory`, or no memories returned after a session | [No memories were generated](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/memory-bank.md.txt#no-memories-generated) |
| Sandbox creation failures | [Sandbox creation issues](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/code-execution.md.txt#sandbox-creation-issues) |
| TLS handshake failures from a custom container (BYOC) agent | [Agent deployed with custom container (BYOC) fails to connect](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/troubleshoot-agent-gateway.md.txt#byoc-ca-fail) |
| `ValueError: Cannot get the Candidate text` | [Content generation errors](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-creation.md.txt#content-generation-errors) |

> [!NOTE]
> **Note:** If your error isn't listed in the table, use the [troubleshooting
> guides](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting#guides), and report the error through [Get support](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting.md.txt#get-support).

## Troubleshooting guides

If you don't have a specific error message, or your error isn't in the [error
catalog](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting#error-catalog), see the following table for the corresponding guide
for your task:

| Task | Guide |
|---|---|
| Installing the Agent Platform SDK and setting up your environment | [Agent Runtime environment setup](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/runtime-setup.md.txt) |
| Creating an agent | [Create an agent](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-creation.md.txt) |
| Deploying an agent to Agent Runtime | [Agent deployment](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-deployment.md.txt) |
| Using a deployed agent | [Use an agent](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/agent-usage.md.txt) |
| Calling an external service from an agent | [Agent Gateway connectivity](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/troubleshoot-agent-gateway.md.txt) |
| Listing, updating, or deleting a deployed agent | [Manage deployed agents](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/managing-deployed-agents.md.txt) |
| Running code in a sandbox | [Code Execution](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/code-execution.md.txt) |
| Generating or retrieving memories | [Agent Platform Memory Bank](https://docs.cloud.google.com/gemini-enterprise-agent-platform/troubleshooting/memory-bank.md.txt) |
| Serving a model or hitting a model quota | [Troubleshooting machine learning services](https://docs.cloud.google.com/gemini-enterprise-agent-platform/machine-learning/troubleshooting.md.txt) |

## Get support

If the guides on this page don't resolve your issue, see [Getting help for
agents](https://docs.cloud.google.com/gemini-enterprise-agent-platform/resources/agent-support) for support packages, community
forums, and bug reporting. For billing questions, see [Billing
questions](https://docs.cloud.google.com/gemini-enterprise-agent-platform/resources/billing-questions).

If you [file a
bug](https://docs.cloud.google.com/gemini-enterprise-agent-platform/resources/agent-support#file_bugs_or_feature_requests), provide the following information:

- Status code
- Error message
- (Optional) Feedback if the error message is wrong, misleading, or not actionable.