> ## Documentation Index
> Fetch the complete documentation index at: https://bifrost-dev.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Work from the failing connection to the agent task, model call, tool call, or callback.

Find the failing hop first. A card fetch, agent request, model call, and push delivery use different endpoints and can require different credentials.

## The card will not fetch

Check the full card URL from Bifrost's network. A URL reachable from your laptop may not be reachable from a container or cluster node. The card must be an A2A card, not an HTML login page.

If it requires authentication, configure **Card fetch options**. Request authentication is used after discovery and cannot fix a protected card fetch. For a private certificate authority or mutual TLS, configure the card connection's TLS settings.

If the card fetch succeeds but calls fail, inspect the interfaces it advertises. Bifrost must reach those addresses too.

## A caller is denied

Check that the agent is enabled and the caller's credential is valid. For restricted agents, grant the virtual key access to that registration.

In Enterprise, check the user's access profile and any project named on the request. Project membership alone does not guarantee an agent grant, and **Allow any virtual key** does not override project restrictions.

If the agent is reached but its LLM or MCP call is denied, grant those resources separately. An agent grant does not grant model or tool access.

See [access control](./access-control) for the configuration and scope rules.

## The card selects the wrong authentication

Use **Configure manually** under request authentication. Supply the credential your server actually accepts, or choose no runtime authentication if the server intentionally accepts the forwarded Bifrost identity instead.

If forwarding and runtime authentication use the same header, choose which value should win. See [header collisions](./authentication#if-both-use-the-same-header).

## The task failed but the request succeeded

An A2A task's state and a gateway operation's status describe different outcomes. Open the conversation, read the failed or rejected task's status message, then inspect its correlated LLM and MCP logs. Task-state filters apply where the row records a state; a SendMessage operation can expose the state only in its returned task payload.

## A stream disconnected

Retrieve the task to see whether it is still working. Reconnect with `SubscribeToTask` if the agent supports it. Disconnecting a client stream does not cancel the task. Use `CancelTask` if you intend to stop the work.

An agent can reject cancellation or subscription. Read the protocol error and its advertised capabilities rather than treating every disconnect as a gateway failure.

## gRPC cannot find the agent

Check the dialed authority. It must contain the registration name as the first DNS label, such as `library-research.a2a.example.com:443`. A generic load-balancer hostname does not identify an agent.

Check wildcard DNS, TLS termination, HTTP/2 forwarding, the public-to-local port mapping, and whether both gRPC server settings were present at startup. With Helm, expose the listener through an additional Service or deployment-specific routing. See [gRPC setup](./configuration#enable-grpc).

## Push notifications are unavailable

Set the gateway's **External Client URL** to an address the agent can reach. Check that the upstream agent supports push notifications and that Bifrost has a configured persistent config store.

If configuration succeeds but delivery fails, distinguish the agent-to-Bifrost **Push notification** from Bifrost-to-client **Push delivery**. Inspect delivery attempts for callback authentication, HTTP errors, or timeouts. Private callback targets are blocked by default. See [push notifications](./push-notifications).

## The logs look incomplete

Check the time filter and permissions first. A long session or event list is paginated. Use the next-page control rather than assuming the first page is the entire conversation.

For missing LLM or MCP logs, inspect [correlation headers](./integrating-your-agent). For missing raw bytes, enable capture before making a new HTTP request. gRPC and local push configuration reads do not provide upstream raw HTTP captures.

Content-logging restrictions may hide bodies while retaining metadata. A file URI can also point to content your browser cannot access. Inspect the structured payload to distinguish a missing file from a failed preview.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.