This guide helps you troubleshoot common issues that may arise when using Factory Bridge. Follow these steps to identify and resolve problems quickly.

​
Connection Issues

​
Bridge Not Connecting to Factory

1

Verify Bridge is Running

First, check if Factory Bridge is running on your system:
  • Look for the Factory Bridge icon in your system tray or menu bar
  • If not visible, try launching Factory Bridge again from your applications folder
2

Check Pairing Code

Verify you’ve entered the correct pairing code:
  • The pairing code should be 6 digits
  • Make sure you’re using the most recent code shown in Factory
  • Try generating a new pairing code in Factory
3

Restart Factory Bridge

If the connection still fails:
  • Right-click the Factory Bridge icon in your system tray
  • Select “Quit”
  • Launch Factory Bridge again
  • Enter the pairing code when prompted
4

Check Session Limit

Factory Bridge currently supports up to 6 concurrent connections:
  • Close some Factory tabs if you have many open
  • Try connecting from a new Factory session
If you’ve recently updated Factory Bridge, you may need to restart your computer for all changes to take effect.

​
Connection Drops Unexpectedly

​
Command Execution Problems

​
Commands Not Executing

1

Verify CLI Tools Are Available

Make sure you can see the CLI tools in Factory:
  1. Ensure you’re using Droid Mode (select from the model dropdown)
  2. Check if the MCP Bridge feature flag is enabled
  3. Refresh your Factory session
2

Check Command Format

Ensure your commands are formatted correctly:
  1. Verify the syntax of your commands
  2. Check that you’re providing all required parameters
  3. Make sure paths don’t contain special characters that need escaping
3

Check Working Directory

Ensure the specified working directory exists and is accessible:
  1. Try using an absolute path instead of a relative path
  2. Verify you have permission to access the directory
  3. Check for typos in the directory path

​
Command Returns Error

​
Process Management Issues

​
Can’t Find Process ID (PID)

1

Locate Process Information

When a process is started through Factory Bridge, the PID is returned in the response:
{
  "pid": 12345
}
Look for this information in Factory’s response after starting a process.
2

Check If Process Is Still Running

Verify if the process is still running:
ps -p 12345
If the process has already terminated, you’ll need to start a new one.

​
Process Terminates Unexpectedly

​
Installation Issues

​
Installation Fails

​
Factory Bridge Won’t Start

1

Check System Resources

Ensure your system has sufficient resources:
  1. Check available memory and disk space
  2. Close unnecessary applications
  3. Restart your computer to free up resources
2

Look for Error Messages

Check for error messages:
  1. Look for error dialogs when launching Factory Bridge
  2. Check system logs for error messages
  3. On macOS, check Console.app for related errors
  4. On Windows, check Event Viewer for application errors
3

Reinstall Factory Bridge

If all else fails, try reinstalling:
  1. Uninstall Factory Bridge completely
  2. Download a fresh copy of the installer
  3. Install Factory Bridge again
  4. Restart your computer after installation

​
Feature Availability Issues

​
Missing CLI Tools

​
Session Limit Reached

1

Understand the Limit

Factory Bridge currently supports up to 6 concurrent connections due to network protocol limitations.
2

Close Unused Sessions

If you’ve reached the limit:
  1. Close unused Factory tabs or sessions
  2. Wait a few minutes for connections to fully close
  3. Try connecting again with a new session
3

Restart Factory Bridge

If closing sessions doesn’t help:
  1. Restart Factory Bridge completely
  2. This will reset all connections
  3. Reconnect with your most important session first

​
Advanced Troubleshooting

​
Check Factory Bridge Logs

​
Reset Factory Bridge

If you’re experiencing persistent issues, you can try resetting Factory Bridge:
1

Quit Factory Bridge

First, completely close Factory Bridge:
  1. Right-click the Factory Bridge icon in your system tray
  2. Select “Quit” or “Exit”
  3. Verify the application has fully closed
2

Clear Configuration

Clear Factory Bridge configuration files: Delete ~/Library/Application Support/Factory Bridge
3

Restart Factory Bridge

Restart Factory Bridge:
  1. Launch Factory Bridge from your applications folder
  2. You’ll be prompted to enter a new pairing code
  3. Enter the pairing code from Factory

​
Getting Additional Help

If you’re still experiencing issues after trying these troubleshooting steps, here are some ways to get additional help:

Report an Issue

Report bugs or issues with Factory Bridge:
  1. Gather relevant error messages and logs
  2. Take screenshots of the issue if applicable
  3. Document the steps to reproduce the problem
  4. Contact Factory support with this information at support@factory.ai

Factory Bridge CLI Tools Reference

For detailed information on all available CLI tools, refer to the Factory Bridge CLI Tools Reference