nautechsystems/nautilus_trader · error

{e}; failed to roll back partial Lighter connection: {shutdo

Error message

{e}; failed to roll back partial Lighter connection: {shutdown_error}

What it means

When spawning the WebSocket consumer during Lighter connection setup fails, the client begins a session shutdown to roll back the partially established connection. If that rollback itself fails, both the original spawn error and the shutdown error are combined into this single anyhow error so no failure context is lost.

Source

Thrown at crates/adapters/lighter/src/execution.rs:4163

                ));
            }
            log::error!("Lighter integrator approval failed; continuing startup: {e:?}");
        }

        self.nonce_ready_connection_epoch
            .store(NONCE_CONNECTION_EPOCH_UNAVAILABLE, Ordering::Release);

        if let Err(e) = self.sync_nonce_from_venue().await {
            log::debug!(
                "Failed to sync Lighter nonce after integrator approval; continuing startup: {e:?}"
            );
        }

        if let Err(e) = self.spawn_ws_consumer().await {
            self.begin_session_shutdown();
            return match self.finish_session_shutdown().await {
                Ok(()) => Err(e),
                Err(shutdown_error) => Err(anyhow::anyhow!(
                    "{e}; failed to roll back partial Lighter connection: {shutdown_error}"
                )),
            };
        }
        self.nonce_ready_connection_epoch
            .store(self.ws_client.connection_epoch(), Ordering::Release);

        if let Err(e) = self.await_account_streams_ready(30.0).await {
            log::warn!("Connect failed after WS started, tearing down: {e}");
            self.begin_session_shutdown();

            if let Err(shutdown_error) = self.finish_session_shutdown().await {
                log::warn!("Failed to finish partial Lighter connection: {shutdown_error}");
            }

            return Err(e);
        }

View on GitHub (pinned to 18893faf8b)

Solutions

1. Inspect both error halves; the original spawn error is the root cause, the shutdown error is secondary
2. Fully drop/recreate the client or task group if its state prevents clean shutdown
3. Ensure the ws endpoint is reachable (network, auth) before reconnecting to avoid the initial spawn failure

// probe reachability before connect
TcpStream::connect((host, port)).await?;

match client.connect().await {
    Err(e) if e.to_string().contains("roll back partial") => {
        // rebuild client; original spawn error is root cause
    }
    other => other?,
}

When it happens

Trigger: spawn_ws_consumer() failed (e.g. WebSocket connect error) AND finish_session_shutdown() also returned an error while tearing down the partially initialized session — typically because pending tasks or the ws client were already in a broken state.

Common situations: Network outage during connect where cleanup also hits the dead connection; reconnect storms leaving the task group mid-shutdown; calling connect after a previous incomplete shutdown.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• std::mem::take(&mut self.shutdown_errors).join("; ")
• Failed to start Lighter task generation: {e}
• Failed to replay SubscribeUser: {e}
• Lighter WebSocket did not reach active state
• reconnection timed out after {}s

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