# Troubleshoot installing and starting MockFlow Bridge

> Fix problems installing, starting and updating MockFlow Bridge: Node.js version, port 21196 in use, no supported agent found, an agent that is not signed in, and update errors.

Source: https://mockflow.com/docs/troubleshoot-starting-mockflow-bridge

MockFlow Bridge runs in a terminal window on your computer. When it does not install, start or find your AI agent, it prints a message that says what is wrong. Find that message below. For the normal setup, see [Set up MockFlow Bridge](/docs/set-up-mockflow-bridge).

## Check what Bridge is doing

Before anything else, run:

```bash
mockflow-bridge status
```

It shows whether Bridge is running, which agent it uses, whether it can read files and which boards are connected. `mockflow-bridge help` lists every command.

## "MockFlow Bridge needs Node.js 18 or newer"

Bridge runs on Node.js version 18 or newer. Check your version:

```bash
node --version
```

If the number is lower than 18, or the command is not found, install the current version from [nodejs.org](https://nodejs.org), open a new terminal window and run `mockflow-bridge` again.

## The install command fails with a permission error

If `npm i -g @mockflow/mockflow-bridge` fails with a permission error, such as `EACCES`, your global npm folder belongs to the administrator account. On macOS or Linux, run the install with `sudo`:

```bash
sudo npm i -g @mockflow/mockflow-bridge
```

## "Port 21196 is in use by another program"

Bridge uses port 21196 on your computer. If an older copy of Bridge is already running, the new one stops it and takes over, so you do not need to close it first. This message means a different program is using the port.

- Close the program that uses port 21196, then run `mockflow-bridge` again.
- If the message says the port is **still busy just after stopping the old bridge**, wait a moment and run `mockflow-bridge` again.

## "No supported agent CLI found"

Bridge could not find an AI agent on your computer, so Mida cannot run on it. Install one and sign in once, then start Bridge again:

| Agent | Install | Sign in |
| --- | --- | --- |
| Claude Code | `npm i -g @anthropic-ai/claude-code` | `claude` |
| Codex | `npm i -g @openai/codex` | `codex login` |
| opencode | See [opencode.ai](https://opencode.ai) | `opencode` |

Or set an API key for BridgeAI, the agent built into Bridge. See [Choose the AI behind MockFlow Bridge](/docs/choose-the-ai-behind-bridge).

## The agent is installed, but Bridge does not find it

Bridge looks for agents in the usual install folders. If you installed an agent somewhere else, for example with a version manager, Bridge may not see it, which is most common on macOS.

- Start Bridge from the same terminal where the agent's command works, for example where `claude --version` prints a version.
- Or tell Bridge which folder holds the agent, replacing the path with the folder that contains the agent's command:

```bash
MFBRIDGE_AGENT_PATH=/path/to/folder mockflow-bridge
```

Run `mockflow-bridge agent` to see which agents Bridge found.

## "Claude Code is not signed in"

Bridge found Claude Code, but Claude Code is not signed in, so Mida shows this message instead of a reply. Open a terminal, run `claude`, sign in once, then start Bridge again with `mockflow-bridge`. Other agents work the same way: run the agent's sign-in command once, such as `codex login`.

## "Unknown agent"

The name after `mockflow-bridge agent` or `--agent` is not one Bridge knows. Use one of the ids that `mockflow-bridge agent` lists, such as `claude`, `codex`, `opencode` or `bridgeai`.

## An "Agent check" warning when Bridge starts

Bridge checks your agent when it starts. A warning box means something may not work as expected:

- **Newer than tested.** Your agent was updated to a version newer than the one Bridge was tested with. Requests usually still work. Update Bridge to the newest version with `mockflow-bridge update`.
- **Output format not recognized.** Bridge cannot read your agent's replies. Update Bridge with `mockflow-bridge update`, or switch to another agent with `mockflow-bridge agent`.

## Update problems

`mockflow-bridge update` installs the newest version of Bridge.

- **"Check your connection, or update by hand"**: Bridge could not reach npm. Check your internet connection, or run `npm i -g @mockflow/mockflow-bridge` yourself.
- **The update needs administrator rights**: Bridge prints the command to run with `sudo`. Run it in your terminal.
- **"A bridge is still running on the old version"**: press Ctrl+C in the Bridge window, then run `mockflow-bridge` again.

## Start over with a clean setup

If Bridge behaves oddly after many changes, reset it. It lists what it will delete and asks before deleting anything.

```bash
mockflow-bridge reset
```

This clears your saved agent choice, attachments and cached data, and keeps your board pairings. To also remove the pairings, run `mockflow-bridge reset --all`; afterwards, pair your boards again with a new code.