Leverage tiers not loaded for {raw_symbol}; cannot validate

Error message

Leverage tiers not loaded for {raw_symbol}; cannot validate leverage {n}:1 (instruments must be initialized before submitting margin orders)

What it means

When submitting a margin (leveraged) spot order, the adapter validates the requested leverage against cached leverage tiers for the raw symbol. If no tiers were loaded into `leverage_tiers_cache` for that symbol, validation cannot proceed and this error is raised. The message states the remedy: instruments (including their leverage tiers) must be initialized before submitting margin orders.

Source

Thrown at crates/adapters/kraken/src/http/spot/client.rs:3147

            builder.expiretm(expire);
        }

        if let Some(dq) = display_qty {
            builder.displayvol(dq.to_string());
        }

        if let Some(ac) = asset_class {
            builder.asset_class(ac);
        }

        if leverage.is_some() && account_type != AccountType::Margin {
            anyhow::bail!("leverage requires spot_account_type=Margin (current: Cash)");
        }

        if let Some(n) = leverage {
            let tiers = self.leverage_tiers_cache.get_cloned(&raw_symbol);
            let (buy_tiers, sell_tiers) = tiers.ok_or_else(|| {
                anyhow::anyhow!(
                    "Leverage tiers not loaded for {raw_symbol}; cannot validate leverage {n}:1 (instruments must be initialized before submitting margin orders)"
                )
            })?;
            let valid_tiers = match order_side {
                OrderSide::Buy => buy_tiers,
                _ => sell_tiers,
            };
            let side_label = match order_side {
                OrderSide::Buy => "buy",
                _ => "sell",
            };

            if valid_tiers.is_empty() {
                anyhow::bail!("Leverage not supported for {raw_symbol} on {side_label} side");
            }

            if !valid_tiers.contains(&(n as i32)) {
                anyhow::bail!(

View on GitHub (pinned to 18893faf8b)

Solutions

Initialize/load instruments (which populates leverage tiers) before submitting leveraged orders.
Confirm the exact `raw_symbol` in the error exists in Kraken's leverage tier data; use the venue's raw symbol spelling.
If you don't want leverage, submit with `leverage: None` so no tier validation is required.
Refresh the tier cache if Kraken recently changed tier data for the pair.

Example fix

// before
client.submit_order(request_with_leverage(5)).await?; // tiers never loaded
// after
client.load_instruments_if_needed().await?; // populates leverage_tiers_cache
client.submit_order(request_with_leverage(5)).await?;

Defensive patterns

Strategy: validation

Validate before calling

fn ensure_tiers_loaded(client: &KrakenSpotHttpClient, raw_symbol: &str, leverage: Option<u32>) -> Result<(), String> {
    if leverage.is_some() && client.leverage_tiers_cache.get(raw_symbol).is_none() {
        Err(format!("leverage tiers missing for {raw_symbol}; initialize instruments first"))
    } else { Ok(()) }
}

Try / catch

if let Err(e) = ensure_tiers_loaded(&client, "XBTUSD", Some(5)) {
    client.load_instruments_if_needed().await?; // then retry once
}
match client.submit_order(req).await { /* ... */ }

Prevention

Run instrument initialization as a mandatory startup step before any order submission
Reject leveraged orders at the strategy layer for symbols outside the loaded universe
Pass leverage: None for cash (non-margin) orders to skip tier validation entirely

When it happens

Trigger: Placing an order with `leverage: Some(n)` for a symbol whose leverage tiers were never fetched/loaded (e.g. instruments initialization skipped, symbol absent from tier data, or trading a pair outside the loaded universe). Note a separate check rejects leverage when account type is Cash.

Common situations: Bypassing the adapter's instrument initialization in tests or scripts; margin order for a brand-new/delisted pair not in tier data; cache cleared or never populated because only Cash instruments were loaded.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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