nautechsystems/nautilus_trader · error · anyhow::Error

Failed to fetch CFM balance summary: {e}

Error message

Failed to fetch CFM balance summary: {e}

What it means

This error wraps any failure from the Coinbase `get_cfm_balance_summary` HTTP call in `request_cfm_balance_summary`. CFM is Coinbase Financial Markets (futures); the method fetches the futures balance summary and returns only its `balance_summary` field. The error means the HTTP request or API response failed — auth problems, missing futures entitlement, network issues, or API errors.

Source

Thrown at crates/adapters/coinbase/src/http/client.rs:1441

        };
        self.inner
            .cancel_orders(&request)
            .await
            .context("failed to cancel orders")
    }

    /// Fetches the CFM (futures) balance summary.
    ///
    /// # Errors
    ///
    /// Returns an error when the HTTP request fails or the response cannot be
    /// deserialized.
    pub async fn request_cfm_balance_summary(&self) -> anyhow::Result<CfmBalanceSummary> {
        let response = self
            .inner
            .get_cfm_balance_summary()
            .await
            .map_err(|e| anyhow::anyhow!("Failed to fetch CFM balance summary: {e}"))?;
        Ok(response.balance_summary)
    }

    /// Fetches margin balances derived from the CFM balance summary.
    ///
    /// # Errors
    ///
    /// Returns an error when the summary cannot be fetched or when a balance
    /// cannot be constructed.
    pub async fn request_cfm_margin_balances(&self) -> anyhow::Result<Vec<MarginBalance>> {
        let summary = self.request_cfm_balance_summary().await?;
        parse_cfm_margin_balances(&summary)
    }

    /// Fetches a margin [`AccountState`] derived from the CFM balance summary.
    ///
    /// # Errors
    ///

View on GitHub (pinned to 18893faf8b)

Solutions

1. Inspect the wrapped inner error to identify auth vs entitlement vs network cause.
2. Confirm the Coinbase account is enrolled in Coinbase Financial Markets (futures).
3. Regenerate API keys with CFM/futures permissions and update credentials.
4. Verify regional availability of Coinbase futures for the account.
5. Retry transient failures with backoff.

Example fix

// before: assumes CFM access always exists
let summary = client.request_cfm_balance_summary().await?;
// after: degrade gracefully when CFM is not enabled
let summary = match client.request_cfm_balance_summary().await {
    Ok(s) => Some(s),
    Err(e) => {
        tracing::warn!("CFM balance summary unavailable (futures not enabled?): {e}");
        None
    }
};

// Only call CFM endpoints when the account is futures-enabled
if !account_config.cfm_enabled {
    tracing::info!("skipping CFM balance summary: futures not enabled");
    return Ok(None);
}

match client.request_cfm_balance_summary().await {
    Ok(summary) => handle(summary),
    Err(e) if e.to_string().contains("401") => refresh_credentials_and_retry().await?,
    Err(e) => tracing::warn!("CFM balance summary failed: {e}"),
}

When it happens

Trigger: Calling `request_cfm_balance_summary` when the CFM balance-summary endpoint returns an error: account not enabled for Coinbase futures, API keys lacking CFM scope, network failure, or non-success HTTP status.

Common situations: Pointing a spot-only Coinbase account at CFM reporting; using API keys created before futures access was granted; hitting the CFM endpoint from an unsupported region; generic network/auth outages during portfolio reconciliation.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• Failed to fetch CFM positions: {e}
• Failed to fetch CFM position '{product_id}': {e}
• Failed to fetch products: {e}
• Failed to fetch order: {e}
• Failed to fetch fills: {e}

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