Fix pairing code problems

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 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, then work down this list:

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

Once the tab is paired again, diagnostics_get 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 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:

Next steps#

• Use one agent across several tabs: how previews and new tabs join the same session.
• Fix an agent that won't connect: when no code ever shows.
• Fix AI agent problems: every other symptom.