nautechsystems/nautilus_trader · error

WS session authentication timed out

Error message

WS session authentication timed out

What it means

During Binance Spot WS trading setup, after `session_logon()` succeeds the adapter waits up to `ws_trading_setup_timeout_ms` (default 10,000 ms) for the sessionLogon success confirmation (the `ws_authenticated` Notify). `wait_for_ws_setup_response` wraps this in `tokio::time::timeout`; if neither the success signal nor a setup error arrives in time, the elapsed timeout is replaced with 'WS session authentication timed out' and adapter connection fails.

Source

Thrown at crates/adapters/binance/src/spot/execution.rs:2006

    setup_errors: &mut tokio::sync::mpsc::UnboundedReceiver<String>,
    timeout_message: &'static str,
) -> anyhow::Result<()> {
    tokio::pin!(success);

    let result = tokio::time::timeout(timeout, async {
        tokio::select! {
            () = &mut success => Ok(()),
            err = setup_errors.recv() => {
                anyhow::bail!(
                    "{}",
                    err.unwrap_or_else(|| "WS setup error channel closed".to_string()),
                )
            }
        }
    })
    .await;

    result.map_err(|_| anyhow::anyhow!(timeout_message))?
}

#[expect(clippy::too_many_arguments)]
fn dispatch_ws_trading_message(
    msg: BinanceSpotWsTradingMessage,
    emitter: &ExecutionEventEmitter,
    http_client: &BinanceSpotHttpClient,
    account_id: AccountId,
    treat_expired_as_canceled: bool,
    clock: &'static AtomicTime,
    dispatch_state: &WsDispatchState,
    ws_authenticated: &tokio::sync::Notify,
    ws_user_data_subscribed: &tokio::sync::Notify,
    ws_setup_error_tx: &tokio::sync::mpsc::UnboundedSender<String>,
    seen_trade_ids: &std::sync::Arc<Mutex<FifoCache<(Ustr, i64), 10_000>>>,
) {
    match msg {
        BinanceSpotWsTradingMessage::OrderAccepted {

View on GitHub (pinned to a4b06ed870)

Solutions

1. Increase `ws_trading_setup_timeout_ms` in the exec client config (e.g. 30_000) and retry connecting
2. Measure latency/connectivity to the Binance WS endpoint and move the runtime closer (or fix proxy/firewall issues)
3. Retry the connect — transient Binance-side slowness usually clears
4. Check logs for preceding auth-rejection or error frames: a hard rejection surfaces a different error, so pure silence points to network/latency rather than credentials

Example fix

# before
config = BinanceExecClientConfig(
    api_key=os.environ["BINANCE_API_KEY"],
    api_secret=os.environ["BINANCE_API_SECRET"],
    use_ws_trading=True,  # default setup timeout 10s
)

# after
config = BinanceExecClientConfig(
    api_key=os.environ["BINANCE_API_KEY"],
    api_secret=os.environ["BINANCE_API_SECRET"],
    use_ws_trading=True,
    ws_trading_setup_timeout_ms=30_000,
)

# Python: pre-flight latency check before building the live node
import time, websocket
start = time.perf_counter()
ws = websocket.create_connection("wss://ws-fapi.binance.com/ws", timeout=5)  # spot: use the spot WS endpoint
rtt_ms = (time.perf_counter() - start) * 1000
ws.close()
setup_timeout_ms = 10_000 if rtt_ms < 1000 else 30_000
config = BinanceExecClientConfig(
    api_key=..., api_secret=..., use_ws_trading=True,
    ws_trading_setup_timeout_ms=setup_timeout_ms,
)

When it happens

Trigger: Building the Binance Spot execution client with WS trading enabled where the `session.logon` request is sent but no response frame arrives within `ws_trading_setup_timeout_ms` — slow or stalled WS connection, high network latency, Binance lagging under load, or a timeout value configured below round-trip time.

Common situations: Hosts far from Binance (cross-region VMs) with handshakes exceeding 10s; congested networks or lossy proxies; Binance maintenance/incident windows; users lowering `ws_trading_setup_timeout_ms` from the default; slow machines where the runtime is starved and the response frame is processed late.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.
• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• WS user data subscription timed out
• WS modify order failed: {e}
• Timeout waiting for account {account_id} to be registered af
• failed to connect Binance Futures private WebSocket
• failed to connect Binance Spot SBE WebSocket: {e}

AI-assisted analysis of nautechsystems/nautilus_trader@a4b06ed870 (2026-08-16). Data as JSON: /api/errors/9f21c267f25ddfa8. Report an issue: GitHub.