nautechsystems/nautilus_trader · error · anyhow::Error

Failed to resolve AX instrument

Error message

Failed to resolve AX instrument {symbol} via GET /instrument: {e}

What it means

The Architect AX adapter could not resolve an instrument by symbol via the venue's GET /instrument endpoint. The underlying HTTP/transport error `e` is wrapped with anyhow to add context identifying the symbol. This adapter throws it because an instrument must be resolved (and cached) before any instrument-specific operations can proceed.

Solutions

  1. Verify the symbol exactly matches an instrument listed on the AX venue (query GET /instruments to list all valid symbols).
  2. Inspect the chained cause (`e`) of the anyhow error to determine whether it is a network failure, HTTP error response, or parse failure and fix accordingly.
  3. Check network connectivity, base URL configuration, and API credentials.
  4. Retry with backoff if the failure is transient (timeout/5xx); the adapter caches successful resolutions so subsequent calls are cheap.
  5. If the symbol was delisted, switch to the currently valid symbol or update configuration.

Example fix

// before: propagating bare error without retry
let instrument = client.resolve_instrument(symbol).await?;
// after: classify and retry transient failures
let instrument = match client.resolve_instrument(symbol).await {
    Ok(i) => i,
    Err(e) if is_transient(&e) => {
        tokio::time::sleep(Duration::from_secs(2)).await;
        client.resolve_instrument(symbol).await?
    }
    Err(e) => return Err(e),
};
Defensive patterns

Strategy: try-catch

Validate before calling

// before calling
fn is_valid_symbol(symbol: &str) -> bool {
    !symbol.is_empty() && symbol.chars().all(|c| c.is_ascii_alphanumeric() || c == '-')
}
if !is_valid_symbol(symbol) { return Err(anyhow::anyhow!("invalid AX symbol: {symbol}")); }

Type guard

fn is_transient(err: &anyhow::Error) -> bool {
    err.chain().any(|c| c.to_string().to_lowercase().contains("timeout")
        || c.to_string().contains("503") || c.to_string().contains("502"))
}

Try / catch

match client.resolve_instrument(symbol).await {
    Ok(i) => i,
    Err(e) if is_transient(&e) => retry_with_backoff(symbol),
    Err(e) => {
        tracing::error!(%symbol, error = ?e, "AX instrument resolution failed");
        return Err(e);
    }
}

Prevention

When it happens

Trigger: Calling the client's instrument resolution method (the async wrapper around request_instrument(symbol, None, None)) when the symbol does not exist on the venue, the symbol string is malformed, the HTTP request fails (network error, non-2xx response, timeout), or the response cannot be parsed into an instrument definition.

Common situations: Typo in symbol (e.g. 'BTC-USDT' vs 'BTCUSDT-PERP'), venue outage or network interruption, expired/invalid API credentials causing HTTP errors, querying a delisted instrument, or a schema change in the AX API breaking parsing of the /instrument response.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors


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

Appendix: source

Thrown at crates/adapters/architect_ax/src/http/client.rs:2369

                Err(e) => {
                    log::warn!("Failed to parse position for {}: {e}", position.symbol);
                }
            }
        }

        Ok(reports)
    }

    async fn resolve_report_instrument(&self, symbol: Ustr) -> anyhow::Result<InstrumentAny> {
        if let Some(instrument) = self.get_instrument(&symbol) {
            return Ok(instrument);
        }

        let instrument = self
            .request_instrument(symbol, None, None)
            .await
            .map_err(|e| {
                anyhow::anyhow!("Failed to resolve AX instrument {symbol} via GET /instrument: {e}")
            })?;
        self.cache_instrument(instrument.clone());
        Ok(instrument)
    }

    /// Cancels all open orders for an instrument.
    ///
    /// # Errors
    ///
    /// Returns an error if the request fails.
    pub async fn cancel_all_orders(&self, instrument_id: InstrumentId) -> Result<(), AxHttpError> {
        let request = CancelAllOrdersRequest::new().with_symbol(instrument_id.symbol.inner());
        self.inner.cancel_all_orders(&request).await?;
        Ok(())
    }
}

View on GitHub (pinned to 18893faf8b)