> ## Documentation Index
> Fetch the complete documentation index at: https://docs.barndoor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitor and troubleshoot Bridge

> For admins: where Bridge's model and tool traffic shows up, how to find launches that failed, how to diagnose a laptop, and fixes for common problems.

This page is for admins once Bridge is rolled out: where to see what governed sessions do, and what to do when someone reports a problem. For what people see on their side, and what they can fix themselves, see [What's blocked and why](https://docs.barndoor.ai/how-tos/barndoor-bridge/whats-blocked.md).

## Where Bridge traffic shows up

Every governed session sends its model traffic through your LLM Gateway and its tool calls through Barndoor, so Bridge usage from every client appears in the same places as the rest of your organization's traffic.

| To see | Go to | Filter or group by |
| - | - | - |
| Model requests, tokens, and cost from Bridge sessions | [LLM Usage Dashboard](https://docs.barndoor.ai/how-tos/read-llm-usage-dashboard.md) (**Reporting → LLM Usage Dashboard**) | **Breakdown → Group by → Client settings** shows governed traffic by the client settings and version it launched with. Group by **AI Agent** for the client, or **User** for the person. |
| Tool calls, errors, and duration | [MCP Usage Dashboard](https://docs.barndoor.ai/how-tos/read-mcp-usage-dashboard.md) (**Reporting → MCP Usage Dashboard**) | **Group by** MCP Server, Tool, User, or AI Agent. Calls to built-in local tools, such as Shell, and to your own local MCP servers appear here too. |
| One server's activity | **MCP Servers → View Details** on the server | Actions, agent usage, tool calls, and an activity log. |
| Every event, in your own storage | [Audit log export](https://docs.barndoor.ai/how-tos/log-export.md) | Model calls and tool calls carry the user and the agent. Shell commands run through Barndoor are recorded as `shell/shell_exec`, without the command text. |
| Launches that failed | **LLM Management → Client settings → Recent failed launches** | See [below](#launches-that-failed). |

Bridge tags each session with its client settings version, so a change you save to client settings shows up as a new row from the next launch, or from a running session's next hourly renewal.

The **AI Agent** each client's traffic is recorded under:

| Client | AI Agent |
| - | - |
| Claude Desktop, Claude Code | **Claude Code** |
| Codex CLI, Codex Desktop | **Codex** |
| Kilo CLI, Kilo Desktop, Kilo in VS Code | **Kilo Code** |
| `barndoor tools call` in a terminal | **Barndoor CLI** |

Claude Desktop launched from Bridge shares the **Claude Code** agent and client settings with Claude Code, so the two can't be told apart in reporting. Your policies can target these agents like any other.

With Bridge governing [MCP only](https://docs.barndoor.ai/how-tos/barndoor-bridge/set-up-your-organization.md#choose-what-bridge-governs), model traffic doesn't go through the LLM Gateway, so it isn't on the LLM Usage Dashboard. With **Models only**, there are no Barndoor tool calls.

What doesn't show up: what a client's own built-in tools do on the laptop, such as a native shell command or file edit, except where it appears in the conversation sent to the model. To route those through Barndoor, see [Client settings](https://docs.barndoor.ai/how-tos/barndoor-bridge/client-settings.md).

## Launches that failed

**LLM Management → Client settings** lists, at the bottom, launches that failed in the last 7 days, grouped by client. Each row has the time, the user, the reason, how often it repeated, and the message the person saw. It's the first place to look when someone says Bridge won't launch.

| Reason | Usual fix |
| - | - |
| **Model access denied** | The person's [Model Access](https://docs.barndoor.ai/how-tos/use-llm-controls.md#model-access) allows no route that fits the client. See [Models](https://docs.barndoor.ai/how-tos/barndoor-bridge/models.md#when-no-model-fits). |
| **Model route unavailable** | Every provider behind the person's routes is unhealthy, or a route resolves to no enabled model. Check **Model Routes**. |
| **Model access unavailable** | Barndoor couldn't read the person's Model Access. Usually brief; ask them to launch again. |
| **Invalid client settings** | The saved client settings can't be applied. Open the client's tab in **Client settings**, fix what it flags, and save. |
| `bridge_capability_needs_mcp` (shown as a code) | Bridge governs **Models only**, and Shell or Network is **Through Barndoor**. See [Bridge governs](https://docs.barndoor.ai/how-tos/barndoor-bridge/client-settings.md#bridge-governs). |
| `bridge_llm_not_governed` (shown as a code) | Bridge governs **MCP only**, and the laptop's Bridge is too old to launch that way. Update Bridge. |
| **CLI out of date** | The laptop runs an older Bridge than the platform needs. Check that your MDM updater is running; see [Install on macOS](https://docs.barndoor.ai/how-tos/barndoor-bridge/install-with-mdm.md#if-a-mac-fails-a-check). |

![Recent failed launches: two Claude rows with the reason Model access denied and the message None of the models you're allowed to use fit Claude Code, and one Codex row with the reason CLI out of date](https://mintcdn.com/barndoor/YcCcMFNMl_NKi3mE/images/barndoor-bridge/client-settings/recent-failed-launches.png?fit=max\&auto=format\&n=YcCcMFNMl_NKi3mE\&q=85\&s=a952e5df96f03fe7975fcec095dcd7e6)

## Diagnose a laptop

Ask the person for two things:

1. **Bridge's log.** In the Bridge window, **Logs → Copy**. On a Mac it's also at `~/Library/Logs/Barndoor/gui.log`; on Windows, in `%LOCALAPPDATA%\Barndoor\Logs`.
2. **`barndoor doctor`** in a terminal. It shows the Bridge version, the Barndoor environment, which managed settings arrived from your MDM, whether direct access to provider APIs is blocked, whether the `barndoor` command is Bridge's, and the last lines of Bridge's log.

![The top of barndoor doctor output: the Bridge version, configuration with product, environment, API URL and launch settings, managed preferences set by MDM including publisher\_keys, the tenant publisher key with its fingerprint and allowed hosts, and the direct inference egress check](https://mintcdn.com/barndoor/0bFGCBNQXYdMP58U/images/barndoor-bridge/barndoor-doctor.png?fit=max\&auto=format\&n=0bFGCBNQXYdMP58U\&q=85\&s=92f2fe7326d8a60c0fcd0b6b608a6e5f)

To check whether a tool is allowed for that person, run `barndoor tools test-policy --harness claude <server> <tool>` on their laptop (or `--harness codex`), for example `barndoor tools test-policy --harness claude filesystem read_text_file`. Without `--harness`, the check ignores policies granted to a specific agent. It prints `LIVE: ALLOWED` or `LIVE: DENIED`.

## Common problems

| Someone reports | Cause | Fix |
| - | - | - |
| `None of the models you're allowed to use fit Claude Code` | Model Access allows no route the client can use. | Allow a route; see [Models](https://docs.barndoor.ai/how-tos/barndoor-bridge/models.md). |
| A route or routing policy is missing from Claude Desktop's picker | Its name doesn't name a Claude model. | Rename it to include `claude` (or `opus`, `sonnet`, `haiku`, `fable`, `anthropic`); see [Models](https://docs.barndoor.ai/how-tos/barndoor-bridge/models.md#claude-desktop). |
| Claude Desktop shows a connection error at launch, or chats get no titles (a bare 429 `rate_limit_error`) | Claude Desktop's own background calls are on a Claude-subscription-only route, which Anthropic refuses for them on every model but Haiku 4.5. | Add an API-key, Bedrock, Vertex, or Foundry target to the route, or point the Haiku route at Haiku 4.5; see [Claude subscription routes](https://docs.barndoor.ai/how-tos/barndoor-bridge/models.md#claude-subscription-routes). |
| A GPT route doesn't appear in Claude Desktop | Claude Desktop shows only Claude models. | People who need GPT use Codex or Kilo. |
| `None of the models you're allowed to use can run in Codex. Codex cannot forward a Claude login…` | Every route the person is allowed uses only a Claude subscription. | Allow a route with an API-key, Bedrock, Vertex, Foundry, or ChatGPT target; see [Models](https://docs.barndoor.ai/how-tos/barndoor-bridge/models.md#codex). |
| `This tool is blocked by policy.` | No policy grants that tool to them. Barndoor denies by default. | Grant it in the [Access Control Center](https://docs.barndoor.ai/how-tos/manage-policies.md). |
| A local tool call is refused, or its output redacted or withheld | A [data protection policy](https://docs.barndoor.ai/how-tos/data-control-center/mcp-policies.md) acted on it, or DLP couldn't be evaluated and Bridge failed closed. A field control on a local server withholds all its calls. | Check the data protection verdict in the audit log. |
| Kilo won't launch | Bridge governs **MCP only**, and Kilo runs only on Barndoor's model provider. | Use **Models and MCP** or **Models only**, or another client. |
| Under **MCP only**, `barndoor` is missing from Claude Desktop, or disappears | Claude Desktop was open when a Bridge older than v0.1.250 added the server. Claude Desktop rewrites its configuration from memory, so a change made while it runs is lost. | Quit Claude Desktop completely, then launch it from Bridge. From v0.1.250, Bridge offers to quit and reopen it. |
| A local tool call returns `runs locally via barndoor-cli and is not executable through the platform router` | The call went to your hosted gateway (a claude.ai connector, or the [managed server for Claude Code](https://docs.barndoor.ai/how-tos/barndoor-bridge/mcp-only.md#managed-barndoor-server-for-claude-code)), which can't reach the laptop. | Use the `barndoor` server Bridge adds; start the client from Bridge. |
| Under **MCP only**, Claude shows two Barndoor connectors, and local tools are refused in Chat | The person also has Barndoor as a connector on claude.ai, and Claude picked it over Bridge's `barndoor`. The hosted connector can't run local tools. | Have them turn their own connector off for chats and Code sessions that need local tools, or remove it. See [MCP only](https://docs.barndoor.ai/how-tos/barndoor-bridge/mcp-only.md#if-people-also-have-the-hosted-barndoor-connector-in-claude). |
| Under **MCP only**, local tool calls from Claude Desktop's Code tab are audited as **Barndoor CLI** | The Code tab used the person's hosted Barndoor connector, couldn't run the local tool through it, and ran `barndoor tools call` in its shell instead. | The same: turn the hosted connector off for that session. |
| An approval card for every shell command | Your policy sets Barndoor's shell tool to **Needs Approval**. | Change the shell tool to **Always Allow** in the policy, or keep it. See [Tool confirmations](https://docs.barndoor.ai/how-tos/tool-confirmations.md). |
| A command is refused however it's written | It matches a **Deny command pattern** in client settings. | See [Client settings](https://docs.barndoor.ai/how-tos/barndoor-bridge/client-settings.md#shell). |
| **Launch Codex Desktop** is missing | The computer has no Codex policy, or Codex Desktop isn't installed. | See [Codex policy](https://docs.barndoor.ai/how-tos/barndoor-bridge/provider-lockdown.md#codex-policy). |
| Codex Desktop is "newer than this Barndoor supports" | Codex Desktop updated itself past the versions Barndoor has reviewed. | Wait for the next Bridge release, turn on **Allow Codex Desktop versions Barndoor hasn't reviewed** on the Codex tab of [Client settings](https://docs.barndoor.ai/how-tos/barndoor-bridge/client-settings.md#where-to-find-them), or [hold Codex Desktop updates](https://docs.barndoor.ai/how-tos/barndoor-bridge/provider-lockdown.md#hold-codex-desktop-updates). |
| `Claude Desktop <version> predates the governed adapter minimum 3.1623.0` | Claude Desktop is too old. | Push a current Claude Desktop. |
| A plugin's MCP server never connects in Claude Desktop | By design: plugin MCP servers would bypass Barndoor. | Connect that server in Barndoor instead. |
| A local MCP server shows **Blocked**, or `failed: key not pinned for this organization` | The laptop's MDM profile doesn't pin your publisher key. | See [Pin the key with MDM](https://docs.barndoor.ai/how-tos/barndoor-bridge/publish-local-mcp.md#step-10-pin-the-key-with-mdm). |
| `barndoor` fails with `parse config cache: not sealed protobuf` | An older standalone `barndoor` earlier on the `PATH` is answering, not Bridge's. | Run `/usr/local/bin/barndoor doctor`; its **Terminal command** section prints the fix. |


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