Skip to content
CoTrading

Learn

Exchange APIs

IBKR error 502 "Couldn't connect to TWS": causes and fixes

CoTrading editorial team

Figures on this page are as of 2026-09. Fees, limits and margin tiers change — check the venue's own docs.

The full message, as it appears in IBKR’s current TWS API error table:

Couldn’t connect to TWS. Confirm that “Enable ActiveX and Socket Clients” is enabled and connection port is the same as “Socket Port” on the TWS “Edit->Global Configuration…->API->Settings” menu.

In one line: your API client tried to open a TCP socket to TWS or IB Gateway and nothing accepted it. Almost always that is because the API is not enabled in the running application, or because your code and the application disagree about the port. This page is for anyone using the TWS API (the official Python, Java, C++ or C# clients, or a wrapper built on them) who needs to find which cause they have without guessing.

What this error actually means

The TWS API is not a web API. It is a local TCP socket to a desktop application that has to be running and logged in — the mechanism is covered in IBKR TWS API setup. Your connect() call names a host, a port and a client ID, and the first thing that happens is an ordinary socket open.

If that socket cannot be opened, the operating system — not TWS — returns the failure, and the API client reports it to you as error 502. IBKR’s connectivity docs say this directly, and add the consequence that trips people up: because TWS did not generate the error, it is not captured in TWS log files.

So the first rule of debugging 502 is: do not look in the TWS logs. There is nothing there. TWS never saw the attempt. Everything you need to check is on the client side of the connection — the application’s settings, the port, and the network path between the two.

Two related points:

  • This is a TWS API code. The numeric codes arrive through the EWrapper.error() callback over the socket. The Client Portal Web API reports failures as HTTP responses instead, so an HTTP 502 status from a web endpoint is a different thing that happens to share a number.
  • 502 is not 326. If you get error 326, client ID already in use, the socket opened fine and TWS rejected your client ID. A 502 means you never got that far.

The usual cause

IBKR’s own summary: most commonly, 502 means TWS is not running with the API enabled, or it is listening on a different socket port. Those are two separate checks.

1. The API is not enabled. In the running application, open Global Configuration → API → Settings and confirm “Enable ActiveX and Socket Clients” is ticked:

  • TWS Classic: Edit → Global Configuration → API → Settings
  • TWS Mosaic: File → Global Configuration, or the cog wheel top right
  • IB Gateway: Configure → Settings → API → Settings

On a fresh TWS install this is off. IB Gateway, by contrast, accepts socket connections by default. That asymmetry is behind a large share of “it worked yesterday on the Gateway, and today I opened TWS instead”.

2. The port does not match. The same settings panel shows a “Socket Port”. The port in your connect() call must equal it. IBKR’s defaults:

TargetDefault port
TWS live7496
TWS paper7497
IB Gateway live4001
IB Gateway paper4002

These are defaults and can be changed, so read the number in the panel rather than trusting the table. A typical Python call on the same machine:

app.connect("127.0.0.1", 7497, 0)   # host, port, clientId

Other causes, in order of likelihood

TWS or IB Gateway is not running, or not logged in. The API needs a running, logged-in instance. A Gateway that was closed overnight, restarted for an update or sitting at its login screen produces exactly this error.

Live and paper are crossed. Paper is a separate login with its own port, not a separate API. Code pointed at 7497 while the running session is live (7496), or the reverse, fails with 502. This one is worth fixing structurally: log the port you connected to at startup, so a mismatch is visible in one line.

TWS and Gateway are crossed. Code written against IB Gateway’s 4002 will not reach TWS on 7497. Switching between the two applications without updating the port is a common way to arrive here.

The wrong host. 127.0.0.1 or localhost is correct only when your code runs on the same machine as TWS. If your client runs in a container or a VM, localhost refers to that container or VM, not to the host where TWS is listening.

Something on the network path is blocking it. When connecting across a network, IBKR lists two further causes: a firewall or antivirus program blocking the connection, and the router’s IP address not being listed under Trusted IPs in TWS. By default TWS does not auto-accept API connections, and IBKR states that untrusted IPs attempting to connect are denied without prompting. Add the address TWS actually sees to Trusted IPs in the same settings panel.

A related but different symptom: when a local connection is not yet trusted, TWS may show a confirmation dialog and the connection waits for someone to click it. That is not a 502 — TWS received the connection — but for an unattended process the outcome is similar. Trusting the local machine is the fix.

How to confirm which one you have

Work through these in order. Each step is cheap and rules out a whole branch.

  1. Is the application running and logged in? Look at the machine, not at your assumptions. A login screen counts as not running.

  2. Is anything listening on the port? From the machine running TWS:

    # macOS / Linux
lsof -iTCP:7497 -sTCP:LISTEN
# Windows
netstat -an | findstr 7497

    Nothing listening means the API is disabled or the port is different. Open the settings panel and read the “Socket Port” value.

  3. Does your code use that port and that host? Print the exact values your client passes to connect(). Configuration layers (environment variables, defaults in a wrapper library, a config file you forgot about) are where the wrong number usually comes from.

  4. If you connect remotely, does a local connection work? Run the same client on the TWS machine against 127.0.0.1. If local works and remote fails, the problem is the network path: firewall, antivirus, or Trusted IPs.

When the connection succeeds you will typically see informational messages through the same error() callback — 2104 “Market data farm connection is OK” and 2106 for the historical data farm. These are not errors. Filter informational codes out of your alerting, or every healthy connect will look like a failure. Error handling patterns for trading APIs covers the wider question of which errors to retry and which to surface.

If 502 appears intermittently on a process that normally connects fine, the application is going away underneath you — a restart, a logout, a crash. That is a reconnection problem rather than a configuration problem, and it is worth handling with backoff rather than a tight retry loop.

FAQ

Why is there nothing about error 502 in the TWS logs?

Because TWS never generated it. IBKR’s documentation explains that when the socket cannot be opened, the operating system returns the error to the API client, which reports it as 502. TWS did not see the attempt, so it has nothing to log. Debug from the client side instead: settings, port, host and network.

Which port should I connect to for IBKR paper trading?

By default, 7497 for TWS paper and 4002 for IB Gateway paper; 7496 and 4001 are the live equivalents. These are editable defaults, so the correct answer is the “Socket Port” shown in Global Configuration → API → Settings of the application you are actually running. The port in your connect() call must match it.

Why does my code connect to IB Gateway but get 502 from TWS?

IB Gateway accepts socket API connections by default, while a fresh TWS install does not. Tick “Enable ActiveX and Socket Clients” in TWS’s API settings, then check that the TWS socket port matches your code — TWS and Gateway use different default ports, so code written for one usually points at the wrong port for the other.

Is IBKR error 502 the same as an HTTP 502 Bad Gateway?

No. The TWS API’s 502 is a numeric code delivered through the EWrapper.error() callback when a socket to TWS or IB Gateway cannot be opened. The Client Portal Web API reports problems as HTTP status codes, and an HTTP 502 there is an unrelated failure that happens to share the number.