# Fix pairing code problems

> Why DiceyTable asks for a new pairing code after a reload, why a fresh code says it did not match, and how to clear a leftover bridge that holds the hub.

- Question: Why does DiceyTable ask me for a new pairing code?
- Source: https://diceytable.com/docs/ai-agents/troubleshooting/pairing-code
- Last verified: 2026-10-09

A tab asks for a new pairing code when the agent session it belonged to has ended. A reload on its own never needs
one. Below you'll find how to tell why the session ended, and what to do about codes that won't take.

A pairing code is the short code your agent shows you, such as `K7P-4QX`. You type it into **Help ▸ Connect AI
agent…** so the tab knows which agent to trust. [Pair a DiceyTable tab with your agent](https://diceytable.com/docs/ai-agents/setup/pairing)
covers the normal steps.

## A reloaded tab asks for a new pairing code

**What should happen.** A paired tab rejoins its agent session by itself after a reload. That goes for the editor, a
preview, a table or the lobby. You don't see a dialog. The tab gets a new tab id and carries on, like a friend who
steps out for snacks and slides back into the game.

The cause of the reload doesn't matter. Maybe you pressed reload. Maybe the browser reloaded the tab after you allowed
pop-ups, or woke it from sleep. Maybe a new version of DiceyTable came out. A tab that sat in the background and missed
its heartbeats rejoins too, the next time it runs. (A heartbeat is a small "still here" message sent on a timer.)

Sometimes the old page is still closing its connection when the new one asks to join. Then the tab tries again a few
times over a few seconds before it gives up.

**When it does ask for a code,** the session it belonged to has ended. Ask your agent to call
[`session_status`](https://diceytable.com/docs/ai-agents/reference/tools/sessions#sessionstatus), then work down this list:

| Cause | How to tell | Fix it |
|---|---|---|
| The session ended | `session_status` shows no session, or a `lastEndReason` such as `user`, `heartbeat-timeout` or `token-revoked` | Ask the agent to call `session_connect`, and type the new code. |
| The bridge restarted | Your MCP client restarted, or `session_status` shows a different session id | A new bridge means a new session. Pair with its code. |
| A leftover bridge holds the hub | `session_status` shows a `Hub:` role of `relay-client`, not `hub` | See the next section. |
| The tab was signed out, or into another account | Pairing again fails with `unauthorized` or `ticket-user-mismatch` | Sign the tab back in to the key's account. |

`lastEndReason` is `user` after a `session_disconnect` call or a click on **Disconnect**.

Once the tab is paired again, [`diagnostics_get`](https://diceytable.com/docs/ai-agents/reference/tools/diagnostics#diagnosticsget) on it shows an
`agent-resume-refused` warning with the reason:

- `expired`: the bridge no longer knew the tab, so the session or the bridge was replaced.
- `already-paired`: another open tab held the same pairing, as a duplicated tab does.

## When a leftover bridge holds the hub

The hub is the one bridge on your computer that tabs connect to, on port 47621. Every other bridge relays through it.
That works, but every tab then talks to **that** bridge's code, which may be an older version than yours. So if you
updated the bridge and a fix doesn't seem to apply, this is why.

**How to tell.** `session_status` shows `Hub: relay-client`. `doctor` says port 47621 is *held by a running DiceyTable
bridge hub*.

**Fix it.**

1. Close the other MCP client that runs a bridge. If there is none, a bridge from an earlier run was left behind. End
   that `node` process (its command line mentions `mcp-bridge`) in Task Manager or with your system's process tool.
2. Ask your agent to reconnect. Its bridge now becomes the hub.
3. Type the new pairing code.

[How the bridge works](https://diceytable.com/docs/ai-agents/concepts/how-it-works) explains the hub and relay clients in plain words.

## Why does a new code say it did not match?

**What you see.** *"That code did not match"* for a code the agent just gave you.

**Why it happens.** If `session_status` shows **no pending code** and a `lastEndReason`, the session ended after the
agent showed you the code. The code ended with it. This often happens when the agent calls `session_disconnect` to
start over. A tab rejoining in the background never uses up or cancels a code.

**Fix it.** Ask the agent for a fresh code. Each code works for 5 minutes and 5 tries.

## What does too many wrong codes mean?

The connect dialog shows one of these messages when a code doesn't work:

| Message | What to do |
|---|---|
| *"That code did not match. 4 attempts left."* | Check the code and type it again. |
| *"That code has expired. Ask your agent for a new one."* | The code is over 5 minutes old. Ask for a new one. |
| *"Too many wrong codes. Ask your agent for a new one and reload this tab."* | You used all 5 tries. Reload the tab first, then type a new code. |

## Next steps

- [Use one agent across several tabs](https://diceytable.com/docs/ai-agents/setup/multiple-tabs): how previews and new tabs join the same
  session.
- [Fix an agent that won't connect](https://diceytable.com/docs/ai-agents/troubleshooting/connection): when no code ever shows.
- [Fix AI agent problems](https://diceytable.com/docs/ai-agents/troubleshooting): every other symptom.