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

Network connectivity problems can cause connection drops:
  1. Check your internet connection
  2. Ensure your firewall isn’t blocking Factory Bridge
  3. If using a VPN, verify it’s not interfering with the connection
  4. Try switching to a different network if possible
System sleep or hibernation can disconnect Factory Bridge:
  1. Check your system’s power settings
  2. Adjust sleep settings to prevent disconnections during active use
  3. Reconnect Factory Bridge after waking your computer
If Factory Bridge has crashed:
  1. Check if the Factory Bridge icon is still in your system tray
  2. If not, relaunch Factory Bridge
  3. Check system logs for error messages
  4. If crashes persist, try reinstalling Factory Bridge

​
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

If you see “command not found” errors:
  1. Verify the command is installed on your system by trying it directly in a terminal
  2. Check if the command is in your system PATH
  3. Use the full path to the executable instead of just the command name
  4. For environment-specific commands, ensure you’re running in the correct environment
If you see “permission denied” errors:
  1. Check if you have permission to run the command
  2. For scripts, ensure they have executable permissions (chmod +x script.sh)
  3. Verify you have access to any files or directories the command is trying to access
  4. For operations requiring elevated privileges, you may need to use sudo (with caution)
If the command is running in the wrong location:
  1. Specify an absolute path for the working directory
  2. Verify the directory exists before running the command
  3. Use pwd command to check the current working directory

​
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

The application may have encountered an error:
  1. Check the output for error messages
  2. Run the command with verbose or debug flags if available
  3. Try running the command directly in a terminal to see if it behaves differently
The process might be terminating due to resource constraints:
  1. Check if your system has sufficient memory and CPU
  2. Look for “out of memory” errors in the output
  3. Consider closing other applications to free up resources
Missing or incompatible dependencies can cause processes to terminate:
  1. Verify all required dependencies are installed
  2. Check version compatibility
  3. Look for dependency-related errors in the output

​
Installation Issues

​
Installation Fails

You may not have sufficient permissions to install Factory Bridge. On macOS, make sure you have permission to install applications
Your system may not meet the requirements:
  1. Check that your operating system version is supported
  2. Verify your system meets the minimum requirements
  3. Look for specific error messages that might indicate compatibility issues

​
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

Terminal tools are only available in Droid Mode:
  1. Open the “Toolkits” selector inside of the chatbox input
  2. Select the “Terminal” toolkit
  3. Retry an existing message or send a new one
Your Factory Bridge version may not be compatible with the Factory platform:
  1. Check for Factory Bridge updates
  2. Download and install the latest version
  3. Restart Factory Bridge after updating

​
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

Factory Bridge logs can provide valuable troubleshooting information:
  • macOS: Look in ~/Library/Logs/Factory\ Bridge
Look for files named bridge-YYYY-MM-DD.log or similar.
If you run into an issue not described above, please share the contents of your log files with our support team.

​
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