Match the message you see to the recovery below. Start with local service health, then check the broker connection, managed AI balance, account access, or export path that owns the failed step.
New to BrokerBridge, or not sure which message you are looking at? Read the plain-language lesson first: Get unstuck: common questions and recovery steps. It covers activation codes, an order you are not sure went through, paused trading, and the Journal in plain language.
For a technical read on current status, check /api/health.
Match the message to the application that shows it, then follow that card.
Where to look: Gateway paper session and paper port 4002
Start Gateway and log in to paper. Confirm the local API settings, choose the IB Gateway paper preset, then test again. Never switch to live port 4001 to make a connection succeed.
Open the matching guide →Where to look: Global Configuration → API → Settings
Keep TWS logged in to paper, confirm socket access and paper port 7497, leave Read-Only API enabled, and repeat the BrokerBridge connection test.
Open the matching guide →Where to look: Masked paper account selector
Select the masked paper account you intend to use. If the mode is not clearly paper, stop. A connected port without verified account identity is not a completed setup.
Open the matching guide →Where to look: Output: 127.0.0.1:49998
Confirm BrokerBridge Link is installed in the NinjaTrader Custom folder. The AddOn loads when NinjaTrader starts; do not attach it to a chart. Check New → NinjaScript Output for the listening address. Keep your connection token private.
Open the matching guide →Where to look: Settings → Broker Accounts → NinjaTrader positions
Treat UNKNOWN as a failed read, not an empty account. Check the BrokerBridge Link AddOn connection and retry the account read. Stop if account identity or positions are still unavailable.
Open the matching guide →Where to look: Unique account selector
Rename the simulation account inside NinjaTrader so the live roster exposes one unique name. Do not bind a funded or evaluation account as a workaround.
Open the matching guide →IB Gateway auto-disconnects daily for maintenance (~midnight ET). Use IBC (IB Controller) for auto-restart. After a restart, repeat the packaged app's Setup Wizard IBKR connection test and confirm it reports the authenticated account, then review IBKR Diagnostics. A port-reachable result alone is not enough. Do not add undocumented timeout keys.
BrokerBridge manages the AI provider credential for you. If a model turn fails to authenticate, check that your AI credit balance is above zero in the dashboard and retry. Test with POST /api/credentials/test. If it persists, contact support.
Increase scan_interval_seconds to reduce request frequency.
Increase ai_provider.timeout_seconds (default: 30). Check your network connection.
Renew at /pricing. API requests return 403 until renewed.
Re-enter credentials through the setup wizard. Your license auto-rebinds to the new machine.
| Error | Solution |
|---|---|
| Config file not found | Use the packaged app Settings, or verify $BROKERBRIDGE_HOME/config.yaml (default: ~/.brokerbridge/config.yaml). Do not create config/config.yaml. |
| account_value <= 0 | Broker connection issue or account not funded |
| Proposal is already approved | Cannot approve or reject a trade plan twice |
| Rate limit exceeded | Wait for Retry-After period |
| Admin authentication required | Set BROKERBRIDGE_ADMIN_TOKEN env var |
The beginner path does not require a terminal. Use the packaged app's in-app Test Connection and IBKR Diagnostics panels, then share the exact error card and sanitized status with support if asked. Do not copy a local bearer token, run undocumented curl commands, or paste credentials into a screenshot or message.