Troubleshoot installing and 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.

Check what Bridge is doing

Before anything else, run:

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:

node --version

If the number is lower than 18, or the command is not found, install the current version from 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:

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:

Or set an API key for BridgeAI, the agent built into Bridge. See Choose the AI behind MockFlow 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:

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.

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.