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
- Check the symbol's underlyingType in the raw exchangeInfo response (GET /fapi/v1/exchangeInfo) to see what value Binance now returns
- Upgrade the nautilusTrader binance adapter to a version that maps the new underlying type
- If upgrading is not possible, skip/filter the affected TRADIFI_PERPETUAL symbols when loading instruments
- 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
- Keep the binance adapter updated so new exchange underlying types are mapped promptly
- Filter TRADIFI_PERPETUAL symbols by supported underlyingType before instrument loading
- Log skipped symbols instead of failing the whole instrument load
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
- Unsupported USD-M contract type
- Symbol ' ' is not trading (status: )
- Unsupported COIN-M contract type
- Invalid tickSize of 0 for symbol
- Binance Futures custom data requires BINANCE venue…
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)