Troubleshooting

Sorted by what you see. You do not know the cause yet — that is why you are here.

If the Bridge printed a block ending in Reference: something, jump straight to By reference code. That code names the cause exactly.

The Broker tab still says "Waiting for handshake"

The Bridge never reached us. Work through it in this order:

Is the Bridge actually running? Not just downloaded — started. On Windows that means a window is open; on Linux, systemctl status ordertune-bridge says active (running).
Did it print an error block? If so, take the reference code below.
Is Trader Workstation running and logged in? The Bridge connects to it first and to us second.
Does the machine have outbound internet access? The Bridge only makes outbound connections; no inbound port and no firewall rule is needed. A proxy that intercepts HTTPS can still break it.

Everything is green, but orders fail

Almost always Read-Only API in Trader Workstation. It permits the connection and the heartbeats and blocks only the sending — which is exactly why it survives until your first real order.

Switch it off under API → Settings, click Apply, and restart Trader Workstation. See Prepare TWS.

The Cockpit reports this at startup, under order access.

Orders sit there and nothing happens

Bypass Order Precautions for API Orders is off. Trader Workstation is holding each order at a confirmation dialog, and if you are not sitting in front of that machine, nobody will ever click it.

Switch it on under API → Precautions. See Prepare TWS.

It worked yesterday and is dead this morning

Interactive Brokers forces Trader Workstation to restart or log out once a day, at a time you set. A Bridge without a logged-in Trader Workstation stands still at the US open.

Set Lock and Exit → Auto restart — not Auto logoff. Once a week Interactive Brokers also asks for a full login, and that one is yours to do. See Prepare TWS.

The badge says "Not reporting"

The connection is authorised, but no heartbeat has arrived for over 90 seconds. No order can be sent in this state. Either the Bridge stopped, the machine went to sleep, or it lost its network.

Check the machine first, the log second.

The badge says "Never seen"

A token was issued and the Bridge has never reported in even once. That is a first-run problem, not a connection that broke — start at Start it and pair it.

I lost my bridge.env

Start the Bridge and pair it again. It writes a new bridge.env itself, and the old token stops working at that moment. Nothing to download, nothing to copy.

I disconnected the Bridge and now it will not start

That is the same situation as above: the file next to the executable is still there, it is just no longer worth anything. Start the Bridge — it notices, opens its window and asks you to pair again.

Up to and including version 0.23.0 it printed an error and stopped instead. Update if you see that.

The pairing code expired

Codes are valid for ten minutes and the window counts down. Click Get a pairing code again — they are single use, and a fresh one costs nothing.

Ordertune shows a different machine than my Bridge window

Then the code you entered is not the one your Bridge is showing. Stop there.

The computer name and the sixteen-character hardware fingerprint are displayed on both sides for exactly this comparison. If they differ, you are about to give a machine that is not yours permission to place orders in your account. Cancel, go back to your own Bridge window, and use the code it shows.

Only ever enter a code your own Bridge window is showing right now. Nobody at Ordertune will ever send you one.

I moved the Bridge to another machine

Start it there and pair it. Pairing reissues the token and rebinds it to the new hardware in one step; there is nothing to reset first.

The old machine stops working at that moment — a connection belongs to one machine at a time.

On Linux only

Five things that can only go wrong on a server, and four of them look like success while they are wrong.

The service will not start

journalctl -u ordertune-bridge -n 50 --no-pager

The Bridge writes the same error block there that it would put on screen on Windows, reference code included. Take the code to the table below.

Trader Workstation is not running, and the message talks about a port

Trader Workstation is a Java desktop application and will not start without a display. On a server without one, install Xvfb or a desktop — see step 1.

The Bridge reports this as a connection failure, because from where it stands that is all it can see: nothing is listening on the port. The real cause is one layer further out.

Pairing said it worked, and the service starts with `env_missing`

The bridge.env was written somewhere other than the program folder. The Bridge looks for it in the working directory, so pairing has to run from /opt/ordertune-bridge:

cd /opt/ordertune-bridge && sudo runuser -u ordertune-bridge -- \
  env HOME=/home/ordertune-bridge ./ordertune-bridge-ibkr --pair

Look for a stray bridge.env in the directory you ran it from, and delete it once the real one is in place — a second copy with a dead token is the kind of thing that confuses the next person.

The log says the data folder is not writable

The service user has no home directory, or it is owned by someone else. This one matters more than it reads:

sudo install -d -o ordertune-bridge -g ordertune-bridge \
  /home/ordertune-bridge/.local/share/ordertune-bridge
sudo systemctl restart ordertune-bridge

That folder holds the record of which orders have already gone out. Without it the Bridge forgets across a restart what it has already sent, and the same order can go out twice. Trading is not stopped while this is broken — which is exactly why the Bridge says so loudly at startup.

`unreadable` on the trade report folder

Trader Workstation and the Bridge are running as different users. Both have to run as ordertune-bridge; see Prepare TWS and the check in Confirm the connection.

By reference code

The code is on the last line of the block the Bridge prints when it cannot start.

Reference	What it means	What to do
`env_missing`	`bridge.env` is not next to the executable.	Put it there, or let the setup window take a pasted copy. See Start it and pair it.
`env_invalid`	The file is there, but a value is missing or unreadable.	Download a fresh pre-filled file rather than editing by hand.
`tws_unreachable`	Nothing answers at that address and port at all.	Trader Workstation is not running, or not logged in.
`tws_wrong_port`	Nothing on your configured port, but something answers on another IBKR port.	The block names which one. Put that number in `IBKR_TWS_PORT`. Files generated before Bridge 0.26.0 call the same setting `IBKR_GATEWAY_PORT`; both spellings keep working, so there is nothing to rename in an existing file.
`tws_api_refused`	Something answers, but the API connection was refused.	Either Enable ActiveX and Socket Clients is off, or `IBKR_CLIENT_ID` is already in use by another connection to the same Trader Workstation. Change it to any other integer.
`token_invalid`	Ordertune rejected the token, or none was sent.	Generate a fresh token and download the new `bridge.env`.
`connection_revoked`	This connection was disconnected in Ordertune.	Set the Bridge up again and replace `bridge.env`.
`ip_mismatch`	The Bridge is running from a different network than the one it registered from.	The connection is bound to the source IP of its first handshake. Run it from a fixed outbound IP, or issue a new token to register the current network.
`fingerprint_mismatch`	The Bridge is running on different hardware than the one it registered on.	Issue a new token. That clears the stored fingerprint, and the next handshake registers this machine.
`fingerprint_already_set`	This token already belongs to another machine.	Use one token per machine. Issue a separate one, or move the Bridge back.
`platform_unreachable`	Ordertune could not be reached at all.	Check outbound internet access and whether a proxy or firewall blocks outbound HTTPS.
`rate_limited`	Too many requests in a short window.	Wait, then restart. If it repeats, more than one Bridge is probably running with the same token.
`wire_contract_mismatch`	This Bridge build and the Ordertune server disagree on the message format.	Restarting does not help. The Bridge is older than the contract the server expects — update it.
`handshake_failed`	Ordertune refused the handshake for another reason.	Check the Broker tab. If the connection looks healthy there, send us the reference and the timestamp.

Warnings about the trade report archive

These do not stop the Bridge. Orders keep going out and fills keep being booked while you see one of them. What most of them tell you is that the safety net is missing: if a fill happens while the Bridge is off, nothing will be able to recover it afterwards.

One of them is the exception, and it is the one you will meet first: exists and is empty right after setup means nothing is wrong yet — there has simply been no trade to report. The others come from step 1, Export Reports, and each names the one thing that is wrong.

Message says	What it means	What to do
`TWS_EXPORT_DIR is not set`	The Bridge does not know which folder to read.	Add `TWS_EXPORT_DIR` to `bridge.env`, or accept the default and create that folder.
`… does not exist`	The path is set but there is no such folder.	Either the export directory in Trader Workstation or the path in `bridge.env` is wrong. They have to be the same folder.
`cannot read …`	The folder exists but the Bridge is not allowed into it.	Fix the read permissions. This also happens when Trader Workstation runs as one user and the Bridge as another.
`… exists and is empty`	The folder is there and holds no report.	Right after setup this is expected — Trader Workstation exports trades, so it writes nothing until something fills. If you did trade today, then Trader Workstation is writing somewhere else: compare the two paths character by character.
`files carry no date in their name`	Trader Workstation is overwriting one single file.	The Export filename field has a name in it. Clear it, so each day gets its own dated file.
`the newest file is from …`	The archive stopped growing.	Either Trader Workstation has not been running, or the periodic export was switched off again.

⚠️

The last two are the expensive ones, because everything looks fine. There is a folder, there are files, the Bridge says nothing about being unable to read them — and yet only one day exists, or the newest day is from last week. Both mean a fill from any other day cannot be recovered.

Reading the log

It rotates daily and is kept for 30 days. It does not live next to the program — from version 0.23.0 on it sits with the other working files, where a tidy-up will not sweep it away.

%LOCALAPPDATA%\Ordertune\Bridge\logs\bridge.log

The Cockpit shows the last 200 lines under Details, together with a Copy diagnostics button that collects version, endpoint, client id, log path and the last heartbeat. Your access token is not included — that is deliberate, because the next thing that happens to a diagnostics block is that it gets pasted into an email.

~/.local/share/ordertune-bridge/logs/bridge.log

Two places, the same lines:

journalctl -u ordertune-bridge -n 100 --no-pager
sudo -u ordertune-bridge tail -n 100 \
  /home/ordertune-bridge/.local/share/ordertune-bridge/logs/bridge.log

There is no Cockpit on a server, so there is no Copy diagnostics button either. Send the journal output instead — and check it for your token before you do, which the Cockpit would have done for you.

If you are chasing a connection problem, set LOG_LEVEL=DEBUG in bridge.env and restart. Set it back to INFO afterwards — DEBUG writes a great deal.

Still stuck

Send us three things: the reference code, the timestamp, and the diagnostics block from the Cockpit. Do not send your bridge.env.

Confirm Updating the Bridge