No usable instruments for {instrument_type:?}, cannot initia

Error message

No usable instruments for {instrument_type:?}, cannot initialize execution client

What it means

During `establish_session`, the execution client fetches OKX instrument definitions for each configured instrument type. If the HTTP instruments response for a type comes back empty, there is nothing to trade on, so the client refuses to initialize. Empty results usually mean the configured instrument type has no listings for the account/venue or the request silently returned nothing.

Source

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

            for instrument_type in &instrument_types {
                let Some(families) =
                    resolve_instrument_families(&self.config.instrument_families, *instrument_type)
                else {
                    continue;
                };

                if families.is_empty() {
                    let (instruments, inst_id_codes) = self
                        .http_client
                        .request_instruments(*instrument_type, None)
                        .await
                        .with_context(|| {
                            format!("failed to request OKX instruments for {instrument_type:?}")
                        })?;

                    if instruments.is_empty() {
                        anyhow::bail!(
                            "No usable instruments for {instrument_type:?}, \
                             cannot initialize execution client"
                        );
                    }

                    log::debug!(
                        "Loaded {} {instrument_type:?} instruments",
                        instruments.len()
                    );

                    self.http_client.cache_instruments(&instruments);
                    all_instruments.extend(instruments);
                    all_inst_id_codes.extend(inst_id_codes);
                } else {
                    for family in &families {
                        let (instruments, inst_id_codes) = self
                            .http_client
                            .request_instruments(*instrument_type, Some(family.clone()))

View on GitHub (pinned to 18893faf8b)

Solutions

Fix the instrument-types configuration to include only types that actually list instruments (e.g. SWAP, FUTURES, SPOT).
For options, configure the required underlyings/families so the correct instruments request is made.
Hit the OKX `/api/v5/public/instruments?instType=...` endpoint manually to confirm data is returned for your parameters.
Retry on transient API failures; the contextual error 'failed to request OKX instruments for {type}' above this one may carry the root cause.

Example fix

// before
instrument_types = ["OPTION"]  # no underlyings configured -> empty response
// after
instrument_types = ["SWAP", "OPTION"]
underlyings = ["BTC-USD", "ETH-USD"]  # required for OPTION requests

Defensive patterns

Strategy: validation

Validate before calling

// verify instruments exist for the configured type before connecting
let resp = reqwest::get("https://www.okx.com/api/v5/public/instruments?instType=SWAP")
    .await?.json::<serde_json::Value>().await?;
if resp["data"].as_array().map_or(true, |a| a.is_empty()) {
    return Err(anyhow::anyhow!("OKX returned no SWAP instruments; fix config"));
}

Prevention

Configure only OKX product types with active listings (SPOT/SWAP/FUTURES/OPTION).
For options, always configure underlyings/families so the correct request is made.
Smoke-test the instruments endpoint with your exact parameters before connecting.

When it happens

Trigger: `connect` -> `establish_session` calls the OKX instruments endpoint for a configured `instrument_type` (SPOT/FUTURES/SWAP/OPTION) and the returned list is empty — e.g. requesting OPTION without an underlying configured when none resolves, or an unsupported/unavailable type.

Common situations: Configuring OPTION instruments without setting the required `underlyings`/family config so the plain-type request returns nothing; querying a product type unavailable on the account's region; transient OKX API issue returning an empty payload that is not treated as an HTTP failure.

Understand the failure class

Background: EmptyResultError / "no results found": when an API or scraper succeeds but returns zero rows — this error's family across 9 libraries.

Related errors

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