26.2 26.1
26.2 26.1

Error Handling Agent Gateway

Errors may occur while working in Scheer PAS. To facilitate troubleshooting, corresponding error and notification messages are displayed in the application. The overview of error messages allows you to identify possible causes and possible solutions. It also refers to documentation pages that contain further details.

Accessing the Agent Gateway

The following problems can occur when you open the Agent Gateway pages:

Problem or Error Message

Possible Reason

Solution

Further Information

The sidebar does not show the Governance group with Providers and Virtual Keys.

You do not have access to the Agent Gateway: you are not an administrator of any platform. A super administrator gets access only as the administrator of a platform.

Ask an administrator of the platform to assign you the group Administrator on that platform.

The page Something Went Wrong opens when you open the address of an Agent Gateway page.

You do not have access to the Agent Gateway, or the Control Hub could not check your access.

Reload the page. If the problem continues, ask an administrator of the platform to check your group.

Agent Gateway

A platform is missing from the Agent Gateway pages.

The pages only show the platforms on which you have access to the Agent Gateway.

Ask an administrator of the missing platform to assign you the group Administrator on it.

Agent Gateway

A button or a field is unavailable, and pointing at it shows You do not have the necessary permissions for this action.

You do not have the permission for this action on the platform.

Ask an administrator of the platform for the permission.

LLM Providers

The following problems can occur while you work with the Providers view and its pages:

Problem or Error Message

Possible Reason

Solution

Further Information

No LLM providers available yet.

None of your platforms has an LLM provider.

Click + New Provider to add an LLM provider.

Creating a Provider

No provider matches the search or the filters.

The current search term and filters exclude every LLM provider.

Adjust or clear your search term and filters.

Working With the Control Hub

The LLM providers cannot be read, and an error message with a retry action is displayed.

The Control Hub could not reach the Agent Gateway feature service, or the service is temporarily unavailable.

Use the retry action to read the LLM providers again. If the problem continues, contact your administrator.

Providers

The column Virtual API Keys or the field Virtual Keys shows a dash (–).

You do not have permission to read the virtual API Keys of the platform, or the virtual API Keys could not be read.

Reload the page. If the problem continues, ask an administrator of the platform for the permission.

Providers

+ New Provider is unavailable.

You may add LLM providers on no platform.

Ask an administrator of the platform for the permission.

Providers

Use 1 to 63 characters (lowercase letters, numbers, and hyphens), the name must not start or end with a hyphen.

The name contains characters that are not permitted, is too long, or starts or ends with a hyphen.

Enter a name that follows the rule.

Creating a Provider

A provider with this name exists on <platform>.

The platform already has an LLM provider with this name, or an LLM provider with this name was removed a few seconds ago.

Enter another name, or wait a few seconds and try again.

Creating a Provider

Enter at least 8 characters.

The provider API Key has fewer than 8 characters.

Enter the complete provider API Key.

Creating a Provider

Choose a platform.

No platform is selected.

Select a platform.

Creating a Provider

Enter 1 to 256 characters. or Enter 1 to 64 characters. or Enter 1 to 256 characters. The deployment name is required when the API version is not v1.

An Azure OpenAI setting is empty or too long: Endpoint and Deployment Name allow 256 characters, API Version allows 64 characters. Deployment Name is required if API Version is given and is not v1.

Correct the setting.

Creating a Provider

The provider refused the provider API Key.

The LLM provider does not accept the provider API Key, for example because it is wrong or expired.

Check the provider API Key in your account at the LLM provider, and enter the correct key.

Creating a Provider

The provider does not know the address of its list of models. Check the settings.

The LLM provider does not know the address that was called, for example because of a wrong API version.

For Azure OpenAI, check Endpoint and API Version.

Creating a Provider

The provider limits the calls of your account. Try again later.

A limit of your account at the LLM provider stopped the call.

Wait, then test again.

Creating a Provider

The provider cannot be reached.

  • The LLM provider gave no answer within 10 seconds.

  • The host is wrong, for example a wrong Azure OpenAI Endpoint.

  • The network of the cluster does not allow the Agent Gateway feature service to reach the LLM provider over HTTPS on port 443, for example api.openai.com, api.anthropic.com, generativelanguage.googleapis.com, or the Azure OpenAI hosts.

Check the Endpoint for Azure OpenAI, and test again later. If the problem continues, ask the operator of your installation to allow access to the hosts of the LLM providers.

Creating a Provider

The provider has not submitted its list of models.

The LLM provider gave an unexpected answer, for example a server error.

Test again later.

Creating a Provider

The connection could not be tested.

  • You may add LLM providers on no platform.

  • For Azure OpenAI, Endpoint is not a host of Azure OpenAI.

  • The Agent Gateway feature service did not answer.

Check that you may add LLM providers on a platform. For Azure OpenAI, enter an Endpoint that ends with .openai.azure.com, .cognitiveservices.azure.com, or .services.ai.azure.com. Otherwise, test again later.

Creating a Provider

Connection works: no models found. for an Azure OpenAI provider, and Default Model proposes no models.

This is expected. The provider API Key of Azure OpenAI cannot list the model deployments.

Enter the name of the model deployment in Default Model yourself.

Creating a Provider

Supplied Models shows Not available, and Default Model proposes no models.

The LLM provider did not give its list of models for the saved provider API Key, or the Agent Gateway feature service did not answer.

Enter a new provider API Key and click Test Connection to find the cause. You can also enter the default model without a proposal.

Managing a Provider

Provider <name> could not be created: <cause>, Provider <name> could not be saved: <cause>, or Provider <name> could not be removed: <cause>

The action failed for the cause in the message.

The page keeps your values. Correct the cause and try again. If the problem continues, contact your administrator.

Providers

The provider <name> does not exist on <platform>.

The LLM provider was removed, the address is wrong, or you do not have access to the Agent Gateway of the platform.

Click Back to Providers and open the LLM provider from the table.

Managing a Provider

An agent has the status Model missing.

The agent called the LLM provider without a model, and the LLM provider has no default model.

Set a default model for the LLM provider, or assign a model to the agent on the agent details page.

Virtual Keys

The following problems can occur while you work with the Virtual Keys view and its pages:

Problem or Error Message

Possible Reason

Solution

Further Information

No Virtual Keys available yet. A Virtual Key always belongs to a provider; create a provider first.

None of your platforms has an LLM provider.

Click Go to Providers and add an LLM provider first.

Creating a Provider

No Virtual Keys available yet. Create one to give agents access to the models of a provider.

None of your platforms has a virtual API Key.

Click + New Virtual Key to create a virtual API Key.

Creating a Virtual Key

No Virtual Key matches the search or the filters.

The current search term and filters exclude every virtual API Key.

Adjust or clear your search term and filters.

Working With the Control Hub

The virtual API Keys cannot be read, and an error message with a retry action is displayed.

The Control Hub could not reach the Agent Gateway feature service, or the service is temporarily unavailable.

Use the retry action to read the virtual API Keys again. If the problem continues, contact your administrator.

Virtual Keys

+ New Virtual Key is unavailable.

You may create virtual API Keys on no platform, or no such platform has an LLM provider. In the last case, pointing at the button shows Create a provider first.

Point at the button to see the reason. Add an LLM provider, or ask an administrator of the platform for the permission.

Virtual Keys

No provider available for <platform>

The selected platform has no LLM provider.

Click the link New provider to add an LLM provider to this platform, or select another platform.

Creating a Provider

The providers could not be read.

The LLM providers of the platform could not be read, or you do not have permission to read them.

Reload the page. If the problem continues, contact your administrator.

Creating a Virtual Key

Select a platform. or Select a provider.

No platform or no LLM provider is selected.

Select a platform and an LLM provider.

Creating a Virtual Key

A Virtual Key with this name already exists on <platform>.

The platform already has a virtual API Key with this name, or a virtual API Key with this name was revoked a few seconds ago.

Enter another name, or wait a few seconds and try again.

Creating a Virtual Key

Enter the name of a model using the provider's spelling.

The entered model name is not valid.

Enter the model name exactly as the LLM provider names it, for example gpt-4o.

Creating a Virtual Key

Attention: This excludes the default model <model> of <provider>. You must assign one of the models permitted here to the agents that are to use this key.

The allowed models do not contain the default model of the LLM provider. A call of an agent that gives no model is rejected.

Add the default model to the allowed models, or assign one of the allowed models to each agent that uses this key.

The column Models shows Misconfigured.

The virtual API Key permits all models and lists other models at the same time, after a manual change outside the Control Hub. It permits no model.

Open the Virtual Key Details page, set the allowed models, and click Save Changes. Alternatively, revoke the virtual API Key.

Managing a Virtual Key

The column Models shows No models.

The virtual API Key permits no model. Its agents cannot call an LLM.

Open the Virtual Key Details page, add the models that the agents may call, and click Save Changes.

Managing a Virtual Key

The column Agents shows a dash (–), or the page shows The agents using this Virtual Key are not known.

The agents of the platform could not be read.

Reload the page. If the problem continues, contact your administrator. Do not revoke the virtual API Key while its agents are not known.

Managing a Virtual Key

Section Agents shows a dash (–) as project and status of an agent.

The Agents view does not show the agent, or you do not have read access to the platform.

Check the agent in the Agents view. Ask an administrator of the platform for read access if needed.

Working With the Agents View

You lost the full virtual API Key.

The Control Hub shows the full key only once, in the dialog Virtual Key Created.

Create a new virtual API Key and assign it to the agents. Then revoke the old virtual API Key.

Creating a Virtual Key

The Virtual Key <name> does not exist on <platform>.

The virtual API Key was revoked, its LLM provider was removed, the address is wrong, or you do not have access to the Agent Gateway of the platform.

Click Back to Virtual Keys and open the virtual API Key from the table.

Managing a Virtual Key

Virtual Key <name> could not be created: <cause>, Virtual Key <name> could not be saved: <cause>, or Virtual Key <name> could not be revoked: <cause>

The action failed for the cause in the message.

The page keeps your values. Correct the cause and try again. If the problem continues, contact your administrator.

Virtual Keys

Calls of Agents Through the Agent Gateway

The Agent Gateway answers a call of an agent with the following errors. Changes in the Control Hub apply to the next call, usually after a few seconds.

Problem or Error Message

Possible Reason

Solution

Further Information

401 Unauthorized

The call has no virtual API Key, or a virtual API Key that is unknown, revoked, or belongs to another LLM provider or platform. The virtual API Keys of a removed LLM provider are removed as well.

Assign a valid virtual API Key of the LLM provider to the agent.

403 Forbidden with The virtual API Key does not permit the model: <model>

The virtual API Key does not permit the model of the call. A call without a model uses the default model of the LLM provider, which must be permitted as well. A call without a model to an LLM provider without a default model is also rejected.

Add the model to the allowed models of the virtual API Key, assign a permitted model to the agent, or set a default model for the LLM provider.

403 Forbidden with The virtual API Key is misconfigured: '*' must be the only entry of its models

The virtual API Key is misconfigured and permits no model.

Set the allowed models on the Virtual Key Details page and save them.

Managing a Virtual Key

400 Bad Request for a virtual API Key that permits all models

The call gives no model and the LLM provider has no default model.

Give a model in the call, assign a model to the agent, or set a default model for the LLM provider.

Managing a Provider

404 Not Found with The agent gateway does not support the path: <path>

The Agent Gateway only supports chat completions (/v1/chat/completions), responses (/v1/responses), and the list of models (/v1/models). Other paths, for example /v1/embeddings, are not supported.

Use one of the supported paths.

Agent Gateway

413 Payload Too Large

The body of the call is larger than 32 MiB.

Reduce the size of the call.

Agent Gateway

The list of models of the Agent Gateway contains only *.

This is expected. The virtual API Key permits all models, and the Agent Gateway does not know the models of the provider API Key.

List the allowed models of the virtual API Key if the agent needs a concrete list.

Managing a Virtual Key

PAS CLI

The following problem can occur when you read the address of the Agent Gateway with the PAS CLI:

Problem or Error Message

Possible Reason

Solution

Further Information

pas platform gateway info fails and names pas.agent-gateway.client.

The configuration stored for the active platform states no address of the Agent Gateway.

Run pas platform login again to read the configuration of the platform again. Then run pas platform gateway info again. If the command fails again, the platform states no Agent Gateway. Contact your administrator.

Command Reference

📘