What causes "Lighter WebSocket initial connection timeout after {} seconds" in nautechsystems/nautilus_trader?

Increase ws_timeout_secs in the WebSocket client configuration to accommodate your network latency.

Lighter WebSocket initial connection timeout after {} second

Error message

Lighter WebSocket initial connection timeout after {} seconds

What it means

Raised when the initial Lighter WebSocket connection does not complete within ws_timeout_secs. connect_with_cancellation wraps the connect future in tokio::time::timeout and bails with this message if the deadline expires. It means the TCP/TLS/WebSocket handshake to Lighter did not finish in time.

Source

Thrown at crates/adapters/lighter/src/websocket/client.rs:487

                .map(|value| value.expose_secret().to_owned()),
        };
        let connect = WebSocketClient::epoch_builder()
            .config(cfg)
            .epoch_handler(message_handler)
            .rate_limiter(ws_message_rate_limiter(&self.url))
            .initial_connect_retry_policy(Self::initial_connect_retry_policy())
            .cancellation_token(cancellation_token.clone())
            .maybe_state_sink(
                self.socket_control
                    .as_ref()
                    .map(SocketControl::sink)
                    .or_else(|| self.socket_sink.clone()),
            )
            .connect();
        let client =
            match tokio::time::timeout(Duration::from_secs(self.ws_timeout_secs), connect).await {
                Ok(result) => result?,
                Err(_) => anyhow::bail!(
                    "Lighter WebSocket initial connection timeout after {} seconds",
                    self.ws_timeout_secs,
                ),
            };

        if cancellation_token.is_cancelled()
            || generation != self.connection_generation.load(Ordering::Acquire)
        {
            client.disconnect().await;

            anyhow::bail!("Lighter WebSocket initial connection cancelled");
        }

        let (cmd_tx, cmd_rx) = tokio::sync::mpsc::unbounded_channel::<HandlerCommand>();
        let (out_tx, out_rx) = tokio::sync::mpsc::unbounded_channel::<NautilusWsMessage>();

        // Capture the connection-mode atomic before moving `client` into the
        // SetClient command below.

View on GitHub (pinned to 18893faf8b)

Solutions

Increase ws_timeout_secs in the WebSocket client configuration to accommodate your network latency.
Verify the stream URL (e.g. wss://mainnet.zklighter.elliot.ai/stream) is reachable: curl or wscat the endpoint.
Check DNS resolution and firewall/proxy rules for outbound wss traffic.
Check Lighter exchange status for outages; retry with backoff if the endpoint is down.
If using connect_with_cancellation, confirm the cancellation token wasn't cancelled mid-connect, which would also prevent completion.

Example fix

// before
let client = LighterWebSocketClient::new(config_with(ws_timeout_secs: 5));

// after
let client = LighterWebSocketClient::new(config_with(ws_timeout_secs: 30));

Defensive patterns

Strategy: retry

Validate before calling

// preflight: endpoint reachability
// tokio::net::TcpStream::connect((host, 443)).await? within your timeout budget

Try / catch

const MAX_RETRIES: usize = 3;
for attempt in 1..=MAX_RETRIES {
    match client.connect().await {
        Ok(()) => break,
        Err(e) if e.to_string().contains("initial connection timeout") => {
            tokio::time::sleep(Duration::from_secs(attempt * 2)).await;
        }
        Err(e) => return Err(e),
    }
}

Prevention

Set ws_timeout_secs generously (>=30s) for high-latency links
Health-check the wss URL in config before starting the node
Monitor exchange status pages for outages
Verify proxy/firewall allows outbound wss

When it happens

Trigger: Calling connect() when the wss handshake to the Lighter stream endpoint takes longer than the configured ws_timeout_secs — slow network, unreachable host, DNS delays, or a too-small timeout value.

Common situations: Misconfigured ws_timeout_secs (e.g. 5s) on a high-latency link; wrong stream URL pointing at a firewalled host; corporate proxy intercepting wss traffic; Lighter endpoint outage.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of nautechsystems/nautilus_trader@18893faf8b (2026-09-08). Data as JSON: /api/errors/67cb5172ae9393f9. Report an issue: GitHub.