Troubleshooting¶

The most common things that go wrong, what they look like, and how to fix them. Organized by symptom — find the section that matches what you're seeing.

If your problem isn't here, email support@ws-trading.co with a description of the symptom and (if possible) the relevant section of your log file — see Where the logs are below.

Bot won't connect to IBKR¶

The dashboard surfaces a Connection failed or similar error when you start the bot, or the data status pill stays at DATA · — and never updates.

Diagnose in this order — the most common cause is at the top.

IB Gateway isn't running¶

WS Terminal can't connect to a Gateway that isn't open. Check:

Is Gateway visible in your taskbar?
Is it logged in? (Not at a username/password screen.)

If Gateway isn't running, launch it from its desktop shortcut, log in, then click Start in the dashboard.

Wrong port for paper vs live¶

Easy to mix up. The Settings → Connection section should show:

4002 if you're using Gateway and paper trading
4001 if you're using Gateway and live trading
7497 if you're using TWS and paper trading
7496 if you're using TWS and live trading

If you've configured port 4001 (Gateway live) but Gateway is logged into a paper account, or vice versa, you'll get a connection failure. Update the port to match what Gateway is actually logged into.

API not enabled in Gateway¶

In Gateway's Configure → Settings → API → Settings:

Enable ActiveX and Socket Clients must be checked
Read-Only API must be unchecked

Full walkthrough in IB Gateway → Step 4.

Trusted IP missing¶

In Gateway's API Settings → Trusted IPs section, 127.0.0.1 must be present. If you're running the bot on a different machine than Gateway, that machine's IP also needs to be on the list.

If your bot was running fine and then suddenly lost its connection — and it's a Saturday or Sunday — IBKR has likely pushed a forced re-authentication. Gateway will have shut itself down. Verify by checking your task manager — no java.exe process means Gateway died.

Relaunch Gateway from its desktop shortcut, log in (the same password you've been using — the rejection that triggered the shutdown is typically spurious), tap 2FA. Bot reconnects within seconds. See Daily runbook → IBKR weekend forced re-login.

Client ID conflict¶

If another tool (an Excel API session, a different bot, a separate TWS connection) is using the same client ID at the same time, Gateway rejects the second connection. Change IBKR Client ID in Settings → Connection to a unique number (any integer, just not one another tool is already using).

Test the connection¶

Settings → Connection has a Test connection button. Click it before clicking Start. It does a quick handshake with Gateway without arming the bot, so you can confirm the connection is good without committing to a session.

License key rejected¶

You get an "Invalid license" or "License not found" error during activation, or the bot won't start because the license isn't recognized.

Wrong Whop account¶

You signed in with a Whop account that doesn't have a WS Terminal subscription on it. Confirm in Whop that the account you used at checkout matches the account you signed into the bot with. If you have multiple Whop accounts, this is the most common cause.

Subscription cancelled or refunded¶

If your subscription has lapsed or been refunded, the cloud no longer recognizes the license. Re-subscribe on Whop, then re-activate.

Whop webhook delay¶

When you first subscribe, the Whop webhook that registers your license can take a minute to fire. If you try to activate immediately and get a "We couldn't find a WS Terminal membership" error, wait 60 seconds and try again. If it persists for more than 5 minutes, email support.

Manual key typo¶

If you're using the manual "I have a license key" tab, copy-paste the entire key including the wsterm_ prefix. The key is case-sensitive. No spaces.

Cloud API unreachable¶

If your machine can't reach api.ws-trading.co, license validation fails. Test:

ping api.ws-trading.co

If that fails, check your internet connection, your firewall settings, and whether anything else on the machine can reach the internet.

License file got corrupted¶

In rare cases, %APPDATA%\WSTerminal\license.json becomes unreadable (disk error, partial write during a crash). Symptom: the bot acts unactivated even though you previously activated it.

Fix: delete %APPDATA%\WSTerminal\license.json and re-run the first-run wizard's activation step.

Dashboard won't load¶

You launch WSTerminal.exe, see the console banner, but http://localhost:8080 either shows a "can't reach this page" error or just spins indefinitely.

Bot hasn't finished starting¶

The web server takes 2-3 seconds after the console banner before it's ready to serve. Wait 10 seconds, refresh. If it still doesn't load, the bot may not have finished initializing — check the console window for error messages.

Port already in use¶

If another process is already using port 8080, the bot can't start the dashboard there. The console window will show a binding error.

Common cause: a previous WSTerminal.exe is still running in the background. Open Task Manager → Background processes, look for WSTerminal.exe, end the task, then try again.

If 8080 is genuinely taken by something else, change the dashboard port in Settings → Connection → Dashboard port, then relaunch the app.

Wrong URL¶

http://localhost:8080 is the correct URL. Common mistakes:

https:// (the dashboard isn't TLS-served on localhost)
localhost:8080 without the http:// (some browsers handle it, some don't)
127.0.0.1:8080 (works fine — same as localhost)

Firewall blocking¶

Windows Defender or a third-party firewall can block localhost connections in rare configurations. If everything else looks right, try temporarily disabling the firewall to test. If that fixes it, add an exception for WSTerminal.exe rather than leaving the firewall off.

Browser cache¶

If the dashboard loaded once and now shows a broken page, force a full reload in your browser (Ctrl+F5 on Windows). The dashboard ships some local assets; an out-of-sync cache can produce odd rendering.

No trades firing¶

The bot is running, the state badge says SCANNING, but no FVGs are getting detected or no entries are filling.

You haven't waited long enough¶

Some days the bot doesn't take a trade at all. The strategy filters out a lot of low-quality candidates. A morning with no FVGs is normal, not broken.

Outside the trade window¶

Check the session clock in the top bar. If you're outside the configured detection start / trade window end, the bot won't take entries.

Default schedule:

Detection starts at 9:30 ET
Trade window starts at 9:33 ET
New entries cut off at end-of-day (4:00 PM ET by default)

If the clock is outside this range, no trades will fire by design.

FVG size threshold too high¶

In Config → FVG detection, Min FVG size points may be set larger than the gaps the current market is forming. On quiet days, the market may not produce any gaps wide enough to qualify.

To diagnose: temporarily lower the threshold and see if detections start firing. If they do, your previous threshold was correctly filtering out low-quality gaps — set it back.

Daily limit reached¶

If you've already hit Max FVG trades per day (default 3) for the day, the bot won't take more entries — the state badge will read DAY DONE.

Same if Daily net stop is enabled and the net win/loss limit has been reached.

To verify: check the Today readout on the Dashboard page. If Wins + Losses already equals or exceeds your daily trade cap, that's why.

Multi-entry "only in profit" gating¶

If you have Multi-entry only in profit on and your existing position is currently underwater, same-direction add-on FVGs will be skipped. The primary entry was fine; subsequent add-ons were filtered.

This is intentional but easy to forget. Verify in Config → Multi- entry.

FVG was detected but the limit order never filled¶

This isn't a "no trades firing" problem — the bot is doing its job correctly. A limit order at your configured entry depth will only fill if price retraces into the FVG. Some days that doesn't happen.

Check the FVGs Detected card on the dashboard — if the FVG is listed with status expired or cancelled, the structure was invalidated before the order could fill. That's the strategy working as designed.

Inverse mode confusion¶

If you have Inverse trades on, the bot trades against the FVG direction. If you see a bullish FVG detected but no long entry placed, that's why — under inverse mode, the bullish FVG triggers a SHORT entry. Verify in Config → FVG detection.

Where the logs are¶

Two log files matter:

`multi_entry_bot.log`¶

The bot's main log file. Lives in the install directory next to WSTerminal.exe. Contains every state transition, FVG detection, order placement, fill, exit, and error.

When asking for support, the relevant section of this log is the single most useful thing you can send. Include:

The 5-10 minutes around when the problem occurred
The full file if the bot crashed or stopped responding

Set the log verbosity in Settings → Diagnostics → Log level:

DEBUG — extremely verbose; useful when chasing a hard problem
INFO — default; one line per significant event
WARNING — only warnings and errors
ERROR — only errors

For routine operation, INFO is right. Bump to DEBUG temporarily when you're trying to capture a specific problem, then back down — DEBUG logs grow fast.

Console window output¶

The terminal that opens when you launch WSTerminal.exe mirrors some of the log content. If the console shows an error and then closes, the same content was written to the log file before the crash — open the log file to read it.

IB Gateway logs¶

If your problem is connection-related, IBKR keeps its own log files in:

C:\Jts\<version>\

with names like api.YYYYMMDD.log and ibgateway.YYYYMMDD.log. Useful when you can't tell if the issue is on the bot side or the broker side.

Bot crashed or froze¶

The console window closed unexpectedly, the dashboard is unresponsive, or the state badge has been stuck on the same state for a long time.

Console window closed¶

The bot has crashed or been terminated. Check multi_entry_bot.log for the last few lines — there's almost always a Python exception traceback right before the crash.

What state survives a crash:

License (lives in %APPDATA%)
Trade history (lives in %APPDATA%)
Active config (lives in %APPDATA%)

What does NOT survive:

Any currently-resting orders are still at the broker — the crash didn't cancel them. Check Gateway and manually cancel if needed.
Any open positions are still at the broker — the crash didn't close them. Check Gateway and decide whether to flatten manually or wait for the next session to relaunch the bot and reconcile.

Relaunch the .exe. On startup the bot will detect any existing position at the broker and pick up management of it (it uses the broker's reported position as the source of truth on reconnect).

Dashboard is unresponsive but console is alive¶

The WebSocket connecting the dashboard to the bot may have gotten stuck. F5 the browser tab. If it reconnects, the dashboard should rehydrate within a few seconds.

If F5 doesn't help, the bot may itself be stuck — Ctrl+C in the console window to stop it gracefully, then relaunch.

State badge stuck for a long time¶

If the state badge has been at IN POSITION for hours and you expect the trade to have closed, first check:

Is the position actually still open at the broker? (Open Gateway, look at Portfolio.)
Are the SL and TP orders still resting? (Gateway → Orders.)

If both are still there, the bot is correctly waiting for one of them to fill. This isn't a stuck state — it's a long trade.

If the position is gone at the broker but the dashboard still shows it, the bot's view has diverged. Click Flatten All to force a reconcile, then stop and restart the bot.

Stop won't stop¶

If clicking Stop in the dashboard doesn't transition the state badge to STOPPED:

Try clicking Flatten All instead — this is more forceful
If that doesn't work, Ctrl+C in the console window
As a last resort, kill WSTerminal.exe from Task Manager

After a forced kill, any working orders at the broker remain there — check Gateway and cancel manually if needed.

Cloud sync issues¶

Coming soon — pending cloud-side audit

A dedicated cloud-sync troubleshooting section is in progress. If you're seeing cloud-related errors in the log file (HTTP 401s against /internal/trade, HMAC signature failures, license tier mismatches with the cloud), email support@ws-trading.co with the relevant log lines and we'll diagnose case by case until this section is published.

Where to go next¶

Daily runbook — what normal operation looks like, so anomalies are easier to spot
Going live — if you're switching from paper and seeing live-specific issues
support@ws-trading.co — if nothing on this page matches