What causes "Failed to register WebSocket handler task: {e}" in nautechsystems/nautilus_trader?

Ensure `connect()` is called inside a live async runtime (e.g. a `#[tokio::test]` or running executor).

Failed to register WebSocket handler task: {e}

Error message

Failed to register WebSocket handler task: {e}

What it means

During `connect`, after the socket is established the client spawns a background handler task via a `TaskSpawner`. If the spawner rejects the task (e.g. the underlying runtime/handle failed to spawn), the client rolls back (`out_rx` is dropped) and returns this error wrapping the spawn error.

Source

Thrown at crates/adapters/okx/src/websocket/client.rs:851

                        }
                        None => {
                            if handler.is_stopped() {
                                log::debug!("Stop signal received, ending message processing",);
                                break;
                            }
                            log::debug!("WebSocket stream closed");
                            break;
                        }
                    }
                }

                log::debug!("Handler task exiting");
            }
        };

        if let Err(e) = handler_spawner.spawn(handler_task) {
            self.out_rx = None;
            anyhow::bail!("Failed to register WebSocket handler task: {e}");
        }

        let set_client_result = {
            let cmd_tx = self.cmd_tx.read().await;
            cmd_tx.send(HandlerCommand::SetClient(client))
        };

        if let Err(e) = set_client_result {
            self.handler_tasks.begin_shutdown();
            self.signal.store(true, Ordering::Release);
            let handler_abort = self.handler_abort.lock().clone();
            handler_abort.cancel();
            let shutdown_result = self.close_stream_task(Duration::from_secs(2)).await;
            self.out_rx = None;
            anyhow::bail!(match shutdown_result {
                Ok(()) => format!("Failed to send WebSocket client to handler: {e}"),
                Err(shutdown_error) => format!(
                    "Failed to send WebSocket client to handler: {e}; handler shutdown failed: \

View on GitHub (pinned to 18893faf8b)

Solutions

Ensure `connect()` is called inside a live async runtime (e.g. a `#[tokio::test]` or running executor).
Inspect the wrapped error `e` for the spawner's underlying failure cause.
Retry the connection after confirming the runtime is healthy; recreate the client if its internal state was rolled back.

Example fix

// before: connecting after the runtime was dropped
let client = OKXWebSocketClient::new(...)?; // runtime shut down
client.connect().await?;
// after: keep the runtime alive while connecting
let rt = tokio::runtime::Runtime::new()?;
rt.block_on(async { client.connect().await })?;

Defensive patterns

Strategy: try-catch

Try / catch

match client.connect().await {
    Err(e) if e.to_string().starts_with("Failed to register WebSocket handler task") => {
        log::error!("runtime cannot spawn tasks: {e}");
        // recreate client inside a healthy runtime, then retry once
    }
    other => other?,
}

Prevention

Call connect() only inside a live async runtime/executor.
Do not tear down the tokio runtime while a client is connecting.
Verify custom TaskSpawner implementations are backed by an active runtime handle.

When it happens

Trigger: `connect()` is called and `handler_spawner.spawn(handler_task)` returns `Err` — the async runtime's task handle is unavailable or shutting down.

Common situations: Connecting from a context where the tokio runtime is being torn down; using a custom spawner bound to a dead/stopped runtime; spawning during process shutdown.

Related errors

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