# Fix AI agent problems > Start with the bridge's doctor command, then find your symptom in one table that points to the fix, from pairing codes and ports to keys and screenshots. - Question: My AI agent isn't working. Where do I start? - Source: https://diceytable.com/docs/ai-agents/troubleshooting - Last verified: 2026-10-09 Start with the three quick fixes below, then run the bridge's self-check, `doctor`. If you're still stuck, find your symptom in the table, which points to the page with the fix. Most problems are small. A port is busy, a key ran out, or the tab just needs a fresh pairing code. You'll be back in the game in a few minutes. ## Try these three first Many problems go away with one of these. Try them in order. 1. **Ask the agent to connect again.** It calls `session_connect` and shows you a fresh pairing code. Type it into **Help ▸ Connect AI agent…** in the tab. 2. **Hard-reload the tab.** Press Ctrl+Shift+R, or Cmd+Shift+R on a Mac. An old cached copy of the site can block the connection. 3. **Restart your MCP client.** The bridge reads your key only when it starts, so a new key or a fresh `login` needs a restart. In Claude Code, `/mcp` can reconnect the server for you. If none of them helps, run `doctor` and read on. ## What does the doctor command check? Run it in a terminal: ```sh npx -y @diceytable/mcp-bridge@1 doctor ``` It checks your side of the connection in one go: - your Node.js version (you need 20.19 or newer) - the five ports the bridge can use, 47621 to 47625 - your access key, the account it belongs to, and when it expires (it warns 7 days ahead) - whether DiceyTable's API answers - your computer's clock (a clock that is minutes off makes pairing fail) - the folders the agent may read files from Then it prints hints for your browser. Each line starts with `[ok]`, `[warn]`, `[FAIL]` or `[info]`. If any check fails, `doctor` exits with status 1. The tab shows the other side. Open **Help ▸ Connect AI agent…** to see the pairing state. Once a tab is paired, the indicator's **Activity…** list shows every call the agent made and how it went. Every failed tool call also carries a short code, such as `ambiguous-tab` or `scope-denied`. Your agent sees the code and usually knows what to do next. If it doesn't, look the code up in [AI agent error codes](https://diceytable.com/docs/ai-agents/reference/errors). ## Find your symptom | What you see | Where to fix it | |---|---| | The browser never asks for local network access, or you clicked **Block** | [Allow local network access for the bridge](https://diceytable.com/docs/ai-agents/setup/local-network-access) | | Safari or Brave won't connect directly | [Allow local network access for the bridge](https://diceytable.com/docs/ai-agents/setup/local-network-access) | | *"Refused to connect"* in the browser console | [Fix an agent that won't connect](https://diceytable.com/docs/ai-agents/troubleshooting/connection) | | `doctor` says a port is held by another program | [Fix an agent that won't connect](https://diceytable.com/docs/ai-agents/troubleshooting/connection) | | *"No AI agent bridge answered on this computer"* | [Fix an agent that won't connect](https://diceytable.com/docs/ai-agents/troubleshooting/connection) | | The tab never says **Agent connected** | [Fix an agent that won't connect](https://diceytable.com/docs/ai-agents/troubleshooting/connection) | | The bridge won't start on Windows | [Fix an agent that won't connect](https://diceytable.com/docs/ai-agents/troubleshooting/connection) | | *"Your DiceyTable bridge is too old"* (or *too new*) | [Fix an agent that won't connect](https://diceytable.com/docs/ai-agents/troubleshooting/connection) | | A reloaded tab asks for a new pairing code | [Fix pairing code problems](https://diceytable.com/docs/ai-agents/troubleshooting/pairing-code) | | *"That code did not match"* for a code you just got | [Fix pairing code problems](https://diceytable.com/docs/ai-agents/troubleshooting/pairing-code) | | `ambiguous-tab`, or a call went to the wrong tab | [Use one agent across several tabs](https://diceytable.com/docs/ai-agents/setup/multiple-tabs) | | `no-token`, `token-expired`, `token-revoked` or `scope-denied` | [Create an API key for your AI agent](https://diceytable.com/docs/ai-agents/setup/api-keys) | | A URL import was refused | [How URL imports are fetched safely](https://diceytable.com/docs/ai-agents/concepts/url-imports) | | Exact panel capture was refused | [Exact panel capture for AI agents](https://diceytable.com/docs/ai-agents/workflows/exact-panel-capture) | | Another screenshot error, such as `over-budget` | [AI agent error codes](https://diceytable.com/docs/ai-agents/reference/errors) | | Publishing stopped: *"Review the credits an AI agent attested"* | [Review credits an AI agent added](https://diceytable.com/docs/ai-agents/concepts/ai-attested-credits) | | `paused`, `human-denied`, `read-only-lease` or any other code | [AI agent error codes](https://diceytable.com/docs/ai-agents/reference/errors) | Not sure the agent is connected at all? [Check your agent is connected](https://diceytable.com/docs/ai-agents/setup/verify) walks you through it in about a minute. ## Still stuck? Collect three things before you ask for help: 1. The full output of `doctor`. 2. The text of the error, word for word, or its code. 3. Which browser you use, and which MCP client (Claude Code, Cursor, and so on). Leave your access key out. `doctor` shows only the first few characters of the key, so its output is safe to send us. Then contact us through the [Help Center](https://diceytable.com/help). The Help Center is also the place for problems that aren't about agents, such as joining a game. ## Next steps - [Fix an agent that won't connect](https://diceytable.com/docs/ai-agents/troubleshooting/connection): the bridge or the tab can't find each other. - [Fix pairing code problems](https://diceytable.com/docs/ai-agents/troubleshooting/pairing-code): the tab keeps asking for a code. - [AI agent limits and quotas](https://diceytable.com/docs/ai-agents/reference/limits): when the agent hits a cap.