CLI troubleshooting

Start with the message the CLI printed. Errors are explicit about which layer refused: authentication, scope, risk gate, venue or input.

Authentication #

`unauthorized` / `HTTP 401`

jw3 auth status      # does a stored token exist and is it accepted?
jw3 auth login --browser

Common causes: the token was revoked in Settings → Harness Access, the machine is new and has no credentials, or a CI job is missing JW3_MCP_PAT.

`missing scope: trade:execute` (or trade:propose)

The token is valid but was minted without that scope. Re-run login with the scopes you need:

jw3 auth login --browser --scope "mcp:read trade:propose trade:execute"

Execution refused even with the scope. The scope is necessary but not sufficient: the kill switch must be off and autonomy must be above Propose only. Both live in Settings → Risk limits.

Connections and venues #

`unknown exchange` / `no active connection`

jw3 connections

The venue must be connected in the app before the CLI can read or trade it. A row with status: active is required; markets tells you whether spot, futures or both work.

Balances look empty on a futures venue. Some exchanges keep spot and futures wallets separate. Read both (jw3 balances and jw3 positions) and check the venue's own dashboard if they disagree.

Installation and runtime #

Rate limits #

Venues throttle. If reads start failing after a polling loop:

• raise the poll interval (--watch 10 instead of --watch 2),
• bound the loop with --polls,
• prefer one positions call over many single-pair reads,
• cache analysis output — intel already caches for 15 minutes.

Stale local state #

Some commands keep small state files under ~/.config/jw3 (or the OS temp directory for trail state). After a crash or a kill -9:

jw3 reconcile --exchange kucoin --pair SOL/USDT

reconcile compares local state with the venue and reports strays. It never trades. A fresh trail state can also refuse to restart for up to 15 minutes to prevent a double-fire; wait it out or remove the stale file.

Output that will not parse #

Errors go to stderr, data to stdout, so --json output stays pipeable:

jw3 positions --exchange kucoin --json 2>/dev/null | jq '.[].pair'

If a command prints a banner before JSON, you are on an older build — re-run the installer.

Getting help with a real error #

Include the command you ran (with secrets removed), the exact message, and your platform. Never paste a token, an API key or a credentials.json file — replace them with <redacted>.