IBKR API Connection Troubleshooting: Fix TWS/Gateway Issues for Options Trading

Quick Answer

The most common IBKR API connection issues and their fixes:

Symptom	Most Likely Cause	Quick Fix
"Connection refused"	API not enabled or wrong port	Check TWS → File → Global Config → API → Enable Socket Clients → port 7496/7497
SSL certificate error	Self-signed cert issue	Restart TWS/Gateway; verify SSL config
Connects then drops	TWS auto-logout or network	Check TWS auto-logout timer; verify network stability
Port in use	Another app on 7496/7497	Change port or close conflicting app
No data in chain	Missing market data subscription	Subscribe to OPRA in IBKR Account Management

For detailed step-by-step fixes, read the full guide below.

Issue 1: "Connection Refused"

Symptoms: OptionTrigger or your trading tool shows "Connection refused" or "Cannot connect to TWS."

Fix Steps

Enable API in TWS/Gateway:
- File → Global Configuration → API → Settings
- ✅ Check "Enable ActiveX and Socket Clients"
- Set port: 7496 (live) or 7497 (paper)
Verify port matches:
- Check your trading tool's configuration
- Port must match TWS side exactly
Check TWS/Gateway is fully loaded:
- Wait for all TWS windows to open and data to populate
- Gateway: wait for the status indicator to show "Connected"
Verify localhost accessibility:
- In TWS API settings, "Allow connections from localhost only" should be checked
- If using an IP-restricted setup, ensure your machine's IP is in the trusted list
Check for port conflicts:
```
# macOS/Linux
lsof -i :7496

# Windows (PowerShell)
netstat -ano | findstr :7496
```
If another application is using the port, close it or change TWS to a different port.

Issue 2: SSL Certificate Errors

Symptoms: "SSL handshake failed," "Certificate validation error," or "Self-signed certificate."

Background

IBKR TWS/Gateway generates a self-signed SSL certificate for local API connections on each startup. Your trading tool needs to trust this certificate or be configured to accept it.

Fix Steps

Restart TWS/Gateway:
- Close completely (check system tray/background processes)
- Relaunch and let it fully initialize
- The certificate regenerates on each launch
For OptionTrigger specifically:
- Follow the SSL Certificate Guide
- The Desktop app handles certificate configuration automatically
Check for proxy interception:
- System proxies (Clash, VPNs with HTTPS inspection) can intercept localhost connections
- OptionTrigger uses tauriFetch instead of browser fetch() for this reason
- Temporarily disable proxy to test if it's interfering
Verify SSL settings in TWS:
- File → Global Configuration → API → Settings
- "Use SSL" should match your trading tool's configuration

Issue 3: Connection Drops During Trading

Symptoms: Connection works initially, then drops after minutes or hours.

Fix Steps

Check TWS auto-logout timer:
- File → Global Configuration → Lock and Exit
- Set "Auto-logoff after" to a longer duration or disable
- IB Gateway has a daily mandatory restart (around midnight ET)
Check network stability:
- WiFi drops, VPN reconnects, and ISP hiccups all break the local API connection
- Use a wired connection for active trading sessions
OptionTrigger auto-reconnect:
- The Desktop app attempts automatic reconnection when connection drops
- If persistent, restart TWS/Gateway first, then the OptionTrigger Desktop app
IBKR server maintenance:
- Check IBKR System Status
- TWS resets daily — usually during off-hours, but confirm for your timezone

Issue 4: Orders Rejected or Not Filling

Error	Meaning	Fix
"No trading permission"	Options permissions not active	Apply in IBKR Account Management
"Order rejected — contract not found"	Invalid symbol, expiry, or strike	Verify the exact contract spec
"Not enough cash/equity"	Insufficient funds or margin	Check buying power; reduce size
"Market data farm connection is broken"	Data subscription issue	Check IBKR data subscriptions

Issue 5: No Data in Options Chain

Fix Steps

Subscribe to OPRA (US options market data) in IBKR Account Management
Verify trading hours — US equity options: 9:30 AM - 4:00 PM ET
Check symbol — symbol must be optionable and traded on OPRA exchanges
Refresh the chain — option chains may need manual refresh in some tools
Paper vs live data — paper accounts may have delayed or limited data

Quick Diagnostic Checklist

Before deep troubleshooting, verify:

TWS/Gateway is running and shows "Connected" to IBKR servers
API is enabled in TWS → Global Configuration → API
Port matches (7496 live / 7497 paper)
No other application using the same port
Firewall allows localhost connections on the API port
SSL configuration is consistent between TWS and trading tool
Options permissions are active on IBKR account
Market data subscriptions are active (for real-time quotes)
Trading during market hours (US equity options: 9:30 AM - 4:00 PM ET)

If all items check out and the issue persists, try the nuclear option: restart TWS/Gateway, restart the trading tool, restart the computer. The IBKR API sometimes needs a clean slate.