nautechsystems/nautilus_trader · error

Unsupported underlying type

Error message

Unsupported underlying type '{underlying_type}' for TRADIFI_PERPETUAL symbol '{}'

What it means

When parsing a Binance USD-M TRADIFI_PERPETUAL instrument, the exchange reports the underlying asset class of the symbol (e.g. EQUITY, COMMODITY). This error is thrown when the underlying type reported by Binance is not one of the asset classes the adapter knows how to map to a Nautilus AssetClass. It indicates a new or unmapped TradFi underlying type from the exchange exchangeInfo payload.

Solutions

  1. Check the symbol's underlyingType in the raw exchangeInfo response (GET /fapi/v1/exchangeInfo) to see what value Binance now returns
  2. Upgrade the nautilusTrader binance adapter to a version that maps the new underlying type
  3. If upgrading is not possible, skip/filter the affected TRADIFI_PERPETUAL symbols when loading instruments
  4. Patch parse_tradifi_asset_class in crates/adapters/binance/src/common/parse.rs to map the new underlying type to the appropriate AssetClass

Example fix

// before (parse.rs)
"COMMODITY" => Ok(AssetClass::Commodity),
_ => anyhow::bail!("Unsupported underlying type ..."),
// after
"COMMODITY" => Ok(AssetClass::Commodity),
"INDEX" => Ok(AssetClass::Index), // map the newly listed underlying type
_ => anyhow::bail!("Unsupported underlying type ..."),
Defensive patterns

Strategy: validation

Validate before calling

const SUPPORTED_UNDERLYING: [&str; 5] = ["EQUITY", "KR_EQUITY", "HK_EQUITY", "PREMARKET", "COMMODITY"];
fn is_supported_tradifi(underlying_type: &str) -> bool {
    SUPPORTED_UNDERLYING.contains(&underlying_type)
}
// check before parsing: assert!(is_supported_tradifi(&symbol.underlying_type));

Type guard

fn is_supported_underlying(u: &str) -> bool {
    matches!(u, "EQUITY" | "KR_EQUITY" | "HK_EQUITY" | "PREMARKET" | "COMMODITY")
}

Prevention

When it happens

Trigger: Calling parse_usdm_instrument (directly or via request_instruments / instrument loading) on a TRADIFI_PERPETUAL symbol whose `underlyingType` field is anything other than EQUITY, KR_EQUITY, HK_EQUITY, PREMARKET, or COMMODITY — e.g. Binance adds a new asset class like 'INDEX' or 'FX' to its USD-M futures.

Common situations: Binance lists a new TradFi perpetual category before the adapter is updated; a stale/older adapter version against a current exchangeInfo; tests feeding synthetic exchangeInfo payloads with an exotic underlyingType.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors


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

Appendix: source

Thrown at crates/adapters/binance/src/common/parse.rs:126

        Err(e) => {
            log::warn!("{e}; using initialization timestamp");
            ts_init
        }
    }
}

fn parse_tradifi_asset_class(symbol: &BinanceFuturesUsdSymbol) -> anyhow::Result<AssetClass> {
    let underlying_type = symbol.underlying_type.as_deref().with_context(|| {
        format!(
            "Missing underlying type for TRADIFI_PERPETUAL symbol '{}'",
            symbol.symbol
        )
    })?;

    match underlying_type {
        "EQUITY" | "KR_EQUITY" | "HK_EQUITY" | "PREMARKET" => Ok(AssetClass::Equity),
        "COMMODITY" => Ok(AssetClass::Commodity),
        _ => anyhow::bail!(
            "Unsupported underlying type '{underlying_type}' for TRADIFI_PERPETUAL symbol '{}'",
            symbol.symbol
        ),
    }
}

/// Returns a currency from the internal map or creates a new crypto currency.
pub fn get_currency(code: &str) -> Currency {
    Currency::get_or_create_crypto(code)
}

/// Extracts filter values from Binance symbol filters array.
fn get_filter<'a>(filters: &'a [Value], filter_type: &str) -> Option<&'a Value> {
    filters.iter().find(|f| {
        f.get("filterType")
            .and_then(|v| v.as_str())
            .is_some_and(|t| t == filter_type)
    })

View on GitHub (pinned to 18893faf8b)