nautechsystems/nautilus_trader · error

invalid Derive subscription channel `{channel}`

Error message

invalid Derive subscription channel `{channel}`

What it means

Raised by the Derive subscription channel parser (a FromStr-style constructor for the subscription enum) when the given channel string does not match any supported Derive WebSocket channel pattern (orderbook, ticker, trades, etc.). It is the fall-through after all known channel formats fail to parse.

Source

Thrown at crates/adapters/derive/src/data.rs:2126

            let (instrument_name, interval) = ticker_channel_parts(channel)?;
            return Ok(Self::Ticker {
                channel: channel.to_string(),
                instrument_name,
                interval,
            });
        }

        if let Some((instrument_type, currency)) = channel
            .strip_prefix("trades.")
            .and_then(|value| value.split_once('.'))
        {
            return Ok(Self::Trades {
                channel: channel.to_string(),
                instrument_type: instrument_type.to_string(),
                currency: currency.to_string(),
            });
        }
        anyhow::bail!("invalid Derive subscription channel `{channel}`")
    }

    fn channel(&self) -> &str {
        match self {
            Self::Orderbook { channel, .. }
            | Self::Ticker { channel, .. }
            | Self::Trades { channel, .. } => channel,
        }
    }

    async fn subscribe(&self, ws: &DeriveWebSocketSubscriptionHandle) -> Result<(), DeriveWsError> {
        match self {
            Self::Orderbook {
                instrument_name,
                group,
                depth,
                ..
            } => {

View on GitHub (pinned to 18893faf8b)

Solutions

1. Use one of the adapter's supported channel names (orderbook, ticker, trades) with the correct format.
2. Prefer constructing subscriptions via the adapter's typed helpers/subscribe APIs instead of raw channel strings.
3. If Derive introduced a new channel, check the adapter version and upgrade or extend the parser.

Example fix

// before
let sub = Subscription::parse("orderbookV2/ETH-USD")?; // unsupported pattern
// after
let sub = Subscription::parse("orderbook/ETH-USD-PERP")?;

const SUPPORTED_CHANNELS: [&str; 3] = ["orderbook", "ticker", "trades"];
assert!(SUPPORTED_CHANNELS.contains(&channel), "unsupported Derive channel: {channel}");

match Subscription::try_from(channel_str) {
    Ok(sub) => subscribe(sub),
    Err(e) => log::error!("{e}; check channel name against Derive adapter docs"),
}

When it happens

Trigger: Parsing or constructing a subscription from a channel string that is not one of Derive's recognized channel names/formats, e.g. typos, unsupported channel kinds, or malformed channel strings containing the channel/instrument/currency components.

Common situations: Hardcoding a channel name from Derive docs for a product type this adapter doesn't parse yet; typos like 'orderbook ' (trailing space) or wrong casing; version drift where Derive added channels the adapter doesn't know.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Derive execution startup teardown failed: {teardown_error}
• failed Derive private WS subscriptions
• WS user data subscription timed out
• subscription confirmation failed: {e}
• joined shutdown errors (std::mem::take(&mut self.shutdown_er

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