Troubleshooting
Solutions for the most common issues. Check /api/health for diagnostic information.
IBKR connection issues
"Cannot connect to IB Gateway"
- 1.Is IB Gateway running? Launch it and log in.
- 2.Is the API enabled? Configure → Settings → API → Enable ActiveX and Socket Clients.
- 3.Does the port match? Gateway default: 4002 (paper), 4001 (live). TWS: 7497.
- 4.Is the client ID in use? Each connection needs a unique client_id.
- 5.Is 127.0.0.1 trusted? Add it to the trusted IP list.
"IB Gateway disconnects after a few hours"
IB Gateway auto-disconnects daily for maintenance (~midnight ET). Use IBC (IB Controller) for auto-restart. Set connection_timeout to handle brief reconnection delays.
AI provider errors
"Authentication failed"
API key may be invalid or expired. Test with POST /api/credentials/test. If using OAuth, re-authenticate through the setup wizard.
"Rate limited" (429)
Increase scan_interval_seconds to reduce request frequency, or upgrade your API plan.
"Request timeout"
Increase ai_provider.timeout_seconds (default: 30). Check your network connection.
License issues
"License expired or invalid" (403)
Renew at /pricing. API requests return 403 until renewed.
"Machine changed"
Re-enter credentials through the setup wizard. Your license auto-rebinds to the new machine.
Common error messages
| Error | Solution |
|---|---|
| Config file not found | Create config/config.yaml or set BROKERBRIDGE_CONFIG_PATH |
| account_value <= 0 | IBKR connection issue or account not funded |
| Proposal is already approved | Cannot approve or reject twice |
| Rate limit exceeded | Wait for Retry-After period |
| Admin authentication required | Set BROKERBRIDGE_ADMIN_TOKEN env var |
Diagnostic commands
terminal
# Check system health
curl http://localhost:8080/api/health | python -m json.tool
# Test IBKR connection
curl -X POST http://localhost:8080/api/credentials/ibkr/test \
-H "Content-Type: application/json" \
-d '{"host": "127.0.0.1", "port": 4002, "client_id": 1}'
# Check credential status
curl http://localhost:8080/api/credentials/status | python -m json.tool
# Check setup status
curl http://localhost:8080/api/setup/status | python -m json.tool