nautechsystems/nautilus_trader · error

Timeout waiting for account {account_id} to be registered af

Error message

Timeout waiting for account {account_id} to be registered after {timeout_secs}s

What it means

`await_account_registered` polls the cache after the private WebSocket session is established, waiting for the OKX account-state event to register the account. If the account is still absent from the cache after `timeout_secs`, the client bails. This indicates the private channel never delivered (or the adapter never processed) the account/balance update needed to build the account state.

Source

Thrown at crates/adapters/okx/src/execution.rs:1289

        if self.core.cache().account(&account_id).is_some() {
            log::info!("Account {account_id} registered");
            return Ok(());
        }

        let start = Instant::now();
        let timeout = Duration::from_secs_f64(timeout_secs);
        let interval = Duration::from_millis(10);

        loop {
            tokio::time::sleep(interval).await;

            if self.core.cache().account(&account_id).is_some() {
                log::info!("Account {account_id} registered");
                return Ok(());
            }

            if start.elapsed() >= timeout {
                anyhow::bail!(
                    "Timeout waiting for account {account_id} to be registered after {timeout_secs}s"
                );
            }
        }
    }

    /// Establishes instrument context, both WebSocket transports, private
    /// subscriptions, and initial account state.
    ///
    /// Any failure leaves partially started transports for
    /// [`Self::teardown_session`].
    async fn establish_session(&mut self) -> anyhow::Result<()> {
        // Reset leaves the old generation canceled until this async boundary can drain it
        if !self.pending_tasks.is_empty()
            || !self.session_tasks.is_empty()
            || !self.pending_tasks.is_open()
            || !self.session_tasks.is_open()
            || self.ws_private.is_active()

View on GitHub (pinned to 18893faf8b)

Solutions

1. Increase the account-registration timeout in the client config (e.g. from 10s to 30–60s).
2. Verify API key/secret/passphrase are correct and have the required permissions (account read + trade).
3. Confirm the configured `account_id` matches the account behind the API keys.
4. Check connectivity/proxy stability and OKX status; inspect logs for private WS login or subscription failures preceding the timeout.

// pre-flight: verify credentials and account before connect
// ensure API key has read+trade scopes and account_id matches the key's account

match client.connect() {
    Err(e) if e.to_string().contains("Timeout waiting for account") => {
        log::warn!("account registration timed out; retrying with backoff");
        tokio::time::sleep(Duration::from_secs(5)).await;
        client.connect()?;
    }
    r => r?,
}

When it happens

Trigger: Calling `connect`/`establish_session` where after login the private WS stream yields no account registration within the timeout — e.g. invalid API keys with insufficient permissions, account-id mismatch between config and the keys' account, network stalls, or events filtered out before reaching the cache.

Common situations: API key created without the required read/trade scopes; configuring an `account_id` that does not correspond to the API key's account; slow network or OKX incident delaying the initial balance snapshot; very small timeout configured.

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

• Timeout waiting for account {account_id} to be registered af
• Timeout waiting for account {account_id} to be registered af
• Timeout waiting for account {account_id} to be registered af
• Timed out joining WebSocket handler task after abort: {error
• WS user data subscription timed out

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