This document is for console users and for developers who integrate with the
`BidiProcessOrder` streaming API. It explains common errors that you might see
in the [Food Ordering AI Agent console](https://foodai.cloud.google.com) or from the
streaming API, what causes them, and how to resolve them.

## Console access errors

The Food Ordering AI Agent console uses the Identity and Access Management (IAM)
roles that are granted on your Google Cloud project. The console reads data with
your credentials, so each page shows only the data that your roles allow. The
following predefined roles apply to Food Ordering AI Agent:

| Role | What the role lets you do |
|---|---|
| Food Ordering Agent Viewer (`roles/foodorderingaiagent.viewer`) | View brands, stores, menus, menu ingestion logs, and order history. |
| Food Ordering Agent User (`roles/foodorderingaiagent.agentUser`) | Process ordering sessions, including sessions in **Agent preview**, and run evaluations. |
| Food Ordering Agent Admin (`roles/foodorderingaiagent.admin`) | Create, update, and delete Food Ordering AI Agent resources. This role includes the permissions of the Viewer and User roles. |

### Failed to load brands

After you select a project and a location, the console lists the brands in that
location. If the console can't list the brands, it shows **Failed to load
brands** with the message "You may not have permission, or the API is
unavailable."

To resolve this error, check the following, and then click **Retry**:

- **Your account has a Food Ordering AI Agent role on the project.** Listing brands requires the `foodorderingaiagent.brands.list` permission, which the Food Ordering Agent Viewer and Food Ordering Agent Admin roles include. If you don't have either role, ask a user who manages access for the project to [grant you access](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/troubleshooting.md.txt#grant-access).
- **Your group membership is active.** If your role is granted to a group, confirm that you're a member of the group. If you were added to the group before you had a Google Account for your email address, you might have received an invitation instead of membership. After you create the Google Account, ask the group owner to add you to the group again.
- **You selected a location that your role allows.** If your role is limited to specific locations, go back to the project selector and, in the **Select
  your location** list, select a location where your role applies. If your role is limited to specific resource types, the role's condition must allow the `Location` resource type.
- **Recent changes have taken effect.** IAM changes can take several minutes to take effect. For more information, see [Access change propagation](https://docs.cloud.google.com/iam/docs/access-change-propagation.md.txt).

If the console lists brands but not the brand that you expect, check that the
selected location is the location of the brand.

### Grant access to the console

To grant Food Ordering AI Agent roles, you need the
`resourcemanager.projects.setIamPolicy` permission on the project. You can grant
roles in the Google Cloud console or by using the Google Cloud CLI. For more
information, see
[Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).

For some brands, you can also grant roles on the **Access management** page of
the Food Ordering AI Agent console:

1. In the Food Ordering AI Agent console, select your project and brand.
2. In the navigation menu, click **Access management**.

   The **Access management** item appears only if you have the
   `resourcemanager.projects.getIamPolicy` permission on the project.
3. Click **Add member**.

4. In the **Member's email address** field, enter one or more email
   addresses, separated by commas, and then click **Add email**.

   The console adds addresses that end with `@googlegroups.com` as groups,
   service account addresses as service accounts, and all other addresses as
   individual users. To add a group that has a different address, enter the
   address with the `group:` prefix, for example
   `group:ordering-team@example.com`.
5. In the **Select Roles** section, select one or more roles.

6. In the **Access Scope Boundary** section, select the scope of the roles:

   - **Global**: the roles apply to all locations and resources in the project.
   - **Regional**: the roles apply only in the locations that you select.
   - **Resource** : the roles apply only to the resource types that you select, such as **Brand** , **Location** , **SessionRecord** , **Store** , **Menu** , or **ChannelConfig**.
   - **Custom**: the roles apply only to the selected resource types in the selected locations.
7. Click **Add**.

A **Regional** , **Resource** , or **Custom** scope adds an
[IAM condition](https://docs.cloud.google.com/iam/docs/conditions-overview.md.txt) to the role
binding. Each console page needs permissions on the resources that it reads. For
example, listing brands checks the `Location` resource, and listing the stores of
a brand checks the `Brand` resource. If you limit the resource types, include
the types for every page that the member needs to use.

## Streaming API errors

When the Food Ordering AI Agent API ends a `BidiProcessOrder` stream with an error, gRPC
clients receive the error's status code and message. WebSocket clients receive
a close frame. The close code depends on the error's status code, and the close
reason contains the error message. If the connection is rejected before the
WebSocket handshake completes, your client receives an HTTP error response
instead of a close frame.

The following table shows how status codes map to WebSocket close codes:

| WebSocket close code | gRPC status codes | Meaning |
|---|---|---|
| `1000` | `OK`, `CANCELLED` | The stream closed without an error. |
| `1007` | `INVALID_ARGUMENT`, `FAILED_PRECONDITION`, `OUT_OF_RANGE` | The API rejected a message or the session configuration. Fix the request before you retry. |
| `1008` | `UNAUTHENTICATED`, `PERMISSION_DENIED`, `NOT_FOUND`, `ALREADY_EXISTS`, `ABORTED`, `UNIMPLEMENTED` | The API couldn't authenticate or authorize the request, or a resource that the request refers to doesn't exist. |
| `1011` | `INTERNAL`, `UNKNOWN`, `DATA_LOSS`, `UNAVAILABLE`, `DEADLINE_EXCEEDED`, `RESOURCE_EXHAUSTED` | A server error or a temporary condition. For internal errors, the message doesn't include details. |

### Session ends before the agent greets the customer

Before the agent starts the conversation, the API validates the initial `Config`
message and loads the store's menu. If this step fails, the stream ends with one
of the following errors.

| Message contains | Status code (close code) | Cause and resolution |
|---|---|---|
| `no menus found for store "STORE"` | `NOT_FOUND` (`1008`) | The API didn't find a menu for the `store` resource name in your `Config` message. For the causes, see [Resolve "no menus found for store" errors](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/troubleshooting.md.txt#menu-not-found). |
| `store project ID ("PROJECT_A") does not match session project ID ("PROJECT_B")` | `INVALID_ARGUMENT` (`1007`) | The `session` and `store` fields refer to different projects. Use the same project ID in both fields. |
| `initial message must contain a config` | `INVALID_ARGUMENT` (`1007`) | The first message on the stream wasn't a `Config` message. Send `Config` as the first message, and send it only once. |
| `failed to extract location ID from path` | `INVALID_ARGUMENT` (`1007`) | The `store` field isn't a full store resource name. Use the format `projects/PROJECT/locations/LOCATION/brands/BRAND/stores/STORE`. |
| `is disabled` | `FAILED_PRECONDITION` (`1007`) | The store's status is disabled. The message includes the brand and store IDs. Enable the store before you start sessions for it. |

For gRPC clients, the `no menus found for store` and project mismatch errors
also include an `ErrorInfo` detail with the domain
`foodorderingaiagent.googleapis.com` and the reason `MENU_NOT_FOUND` or
`PROJECT_ID_MISMATCH`.

If the stream ends with `PERMISSION_DENIED` (close code `1008`), the principal
that your client authenticates as doesn't have the
`foodorderingaiagent.sessions.process` permission for the session. Grant the
Food Ordering Agent User role (`roles/foodorderingaiagent.agentUser`) to the
principal. For more information, see
[Authentication](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/ordering-integration.md.txt#authentication).

### Resolve "no menus found for store" errors

The API looks for the menu whose store exactly matches the `store` resource name
in your `Config` message. This error occurs in the following cases:

- **No menu exists for the store yet.** Create a menu for the store before you start sessions for it. In the Food Ordering AI Agent console, check that the store's menu appears on the **Menus** page.
- **The store ID doesn't exactly match the store ID of the menu.** For example, a store ID that's missing a prefix or leading zeros doesn't match. Use the exact store resource name of the store's menu.
- **The location isn't the location where the menu was created.** Use the same location, such as `us`, in the WebSocket URL and in the `session` and `store` fields. `global` isn't a Food Ordering AI Agent location. For the supported locations, see [Food Ordering AI Agent locations](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/locations.md.txt).

### Session ends during the conversation

| Message or behavior | Status code (close code) | Cause and resolution |
|---|---|---|
| `input audio size SIZE exceeds maximum allowed size of 25600 bytes` | `INVALID_ARGUMENT` (`1007`) | An `AudioInput` message contained more than 25,600 bytes of audio. Send smaller audio chunks. If you enable echo cancellation, the limit applies to the combined customer and crew audio in each message. |
| `received config message in the main loop` | `INVALID_ARGUMENT` (`1007`) | The client sent a second `Config` message on the same stream. Send `Config` only as the first message. |
| `internal error`, or any error with close code `1011` | `INTERNAL`, `UNAVAILABLE`, or another code that maps to `1011` | A server error or a temporary condition. Reconnect and send the same `Config` message with the same `session` ID to resume the session. If the error persists, [collect the session details and contact support](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/troubleshooting.md.txt#contact-support). |
| The stream closes without an error before the order is complete. | `OK` (`1000`) | The API ends a session if it doesn't receive any message from your client for 60 seconds. For voice sessions, keep streaming audio input for as long as the session is active. |

### Errors in Agent preview

**Agent preview** in the Food Ordering AI Agent console starts sessions with the
same API that your clients use, so it returns the same errors. If a session in
**Agent preview** fails, the console shows **Session ended abruptly due to an
error: Server-side error during session:** followed by the error message and its
code. For the meaning of the message, see the tables in
[Session ends before the agent greets the customer](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/troubleshooting.md.txt#session-start-errors) and
[Session ends during the conversation](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/troubleshooting.md.txt#in-session-errors).

To start sessions in **Agent preview** , you need the
`foodorderingaiagent.sessions.process` permission, which the Food Ordering Agent
User and Food Ordering Agent Admin roles include. The Food Ordering Agent Viewer
role doesn't include this permission.

## Find failed sessions in Order history

The **Order history** page shows an outcome for each session. The following
outcomes indicate that a drive-thru session ended early or with an error:

| Outcome | Meaning |
|---|---|
| **Disconnected immediately server error** | Before the agent took any action, the session ended with an `INTERNAL` or `UNAVAILABLE` error. |
| **Disconnected immediately unknown** | Before the agent took any action, the session ended with a status code other than `OK`, `CANCELLED`, `INTERNAL`, or `UNAVAILABLE`, for example, `NOT_FOUND` or `INVALID_ARGUMENT`. |
| **Disconnected immediately client cancellation** | The client cancelled the stream before the agent took any action. |
| **Disconnected immediately normal** | The stream closed without an error before the agent took any action. |
| **Order submission error** | The order failed to submit to the point-of-sale (POS) system. |
| **Error** | The session ended because of an error, or the session doesn't match any other outcome. |

In the outcome filter, the **Error** group includes **Order submission error** ,
**Error** , and **Disconnected immediately server error** . To investigate a
session, click its row to open the session details, and use the session ID when
you [contact support](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/troubleshooting.md.txt#contact-support).

## Agent repeats a retry message and then ends the session

For each turn, the agent sends its instructions, the store's menu, and the
conversation history to the model. If this input is larger than the model can
accept, the agent can't generate a response. In this case, the customer hears a
generic retry message, such as "Hmm, I'm having trouble with that. Do you want
me to try again?" After repeated failures, the session ends. Depending on the
agent's configuration, the stream can instead end with close code `1007` and a
message that contains `Input size exceeds the maximum model context window
limit`.

A menu that contains many entries that customers can't order can cause this
issue. The limit applies to the total size of the menu and the instructions,
not to a fixed number of items.

To reduce the size of the menu, create a new menu that includes only the items
that customers can order in the channel. For example, remove delivery-only
items, duplicate items, and entries that aren't food or drink products. If you
create menus from another system, remove these entries from the source data
before you create the menu. For more information about creating menus, see
[Integrating menu data using the API](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/menu-integration.md.txt).

## Information to collect before you contact support

If you can't resolve an error, collect the following information before you
contact your Google representative:

- The `session` resource name from the `Config` message, which includes the session ID.
- The `store` resource name from the `Config` message.
- The location in the WebSocket URL or gRPC request.
- The approximate start time of the session, including the time zone.
- The gRPC status code and message, or the WebSocket close code and close reason.