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 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.listpermission, 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. - 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
Locationresource type. - Recent changes have taken effect. IAM changes can take several minutes to take effect. For more information, see Access change propagation.
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.
For some brands, you can also grant roles on the Access management page of the Food Ordering AI Agent console:
- In the Food Ordering AI Agent console, select your project and brand.
In the navigation menu, click Access management.
The Access management item appears only if you have the
resourcemanager.projects.getIamPolicypermission on the project.Click Add member.
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.comas 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 thegroup:prefix, for examplegroup:ordering-team@example.com.In the Select Roles section, select one or more roles.
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.
Click Add.
A Regional, Resource, or Custom scope adds an
IAM condition 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. |
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.
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 thesessionandstorefields.globalisn't a Food Ordering AI Agent location. For the supported locations, see Food Ordering AI Agent locations.
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. |
| 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 and Session ends during the conversation.
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.
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.
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
sessionresource name from theConfigmessage, which includes the session ID. - The
storeresource name from theConfigmessage. - 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.