{"record":{"id":"2ca18e4ce2b62490","repo":"nautechsystems/nautilus_trader","slug":"failed-to-register-websocket-handler-task-e-2ca18e","errorCode":null,"errorMessage":"Failed to register WebSocket handler task: {e}","messagePattern":"Failed to register WebSocket handler task: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/adapters/okx/src/websocket/client.rs","lineNumber":851,"sourceCode":"                        }\n                        None => {\n                            if handler.is_stopped() {\n                                log::debug!(\"Stop signal received, ending message processing\",);\n                                break;\n                            }\n                            log::debug!(\"WebSocket stream closed\");\n                            break;\n                        }\n                    }\n                }\n\n                log::debug!(\"Handler task exiting\");\n            }\n        };\n\n        if let Err(e) = handler_spawner.spawn(handler_task) {\n            self.out_rx = None;\n            anyhow::bail!(\"Failed to register WebSocket handler task: {e}\");\n        }\n\n        let set_client_result = {\n            let cmd_tx = self.cmd_tx.read().await;\n            cmd_tx.send(HandlerCommand::SetClient(client))\n        };\n\n        if let Err(e) = set_client_result {\n            self.handler_tasks.begin_shutdown();\n            self.signal.store(true, Ordering::Release);\n            let handler_abort = self.handler_abort.lock().clone();\n            handler_abort.cancel();\n            let shutdown_result = self.close_stream_task(Duration::from_secs(2)).await;\n            self.out_rx = None;\n            anyhow::bail!(match shutdown_result {\n                Ok(()) => format!(\"Failed to send WebSocket client to handler: {e}\"),\n                Err(shutdown_error) => format!(\n                    \"Failed to send WebSocket client to handler: {e}; handler shutdown failed: \\","sourceCodeStart":833,"sourceCodeEnd":869,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/18893faf8b356be3320add8de2f861b0b647cf06/crates/adapters/okx/src/websocket/client.rs#L833-L869","documentation":"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.","triggerScenarios":"`connect()` is called and `handler_spawner.spawn(handler_task)` returns `Err` — the async runtime's task handle is unavailable or shutting down.","commonSituations":"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.","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."],"exampleFix":"// before: connecting after the runtime was dropped\nlet client = OKXWebSocketClient::new(...)?; // runtime shut down\nclient.connect().await?;\n// after: keep the runtime alive while connecting\nlet rt = tokio::runtime::Runtime::new()?;\nrt.block_on(async { client.connect().await })?;","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"match client.connect().await {\n    Err(e) if e.to_string().starts_with(\"Failed to register WebSocket handler task\") => {\n        log::error!(\"runtime cannot spawn tasks: {e}\");\n        // recreate client inside a healthy runtime, then retry once\n    }\n    other => other?,\n}","preventionTips":["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."],"tags":["okx","websocket","task-spawn","runtime"],"backgroundTag":"module-init-failed","analyzedSha":"18893faf8b356be3320add8de2f861b0b647cf06","analyzedAt":"2026-09-08T20:49:34.690Z","contentChangedAt":"2026-09-08T20:49:34.690Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}