nautechsystems/nautilus_trader · error

Invalid venue order ID

Error message

Invalid venue order ID

What it means

NautilusTrader's Binance Spot adapter converts a VenueOrderId into the numeric i64 orderId that Binance's REST API expects. This error is thrown when the ID string cannot be parsed as an i64, meaning the ID does not look like a Binance order ID (which are positive integers). It guards query_order and related calls against sending malformed identifiers to the exchange.

Source

Thrown at crates/adapters/binance/src/spot/http/client.rs:3165

        &self,
        account_id: AccountId,
        instrument_id: InstrumentId,
        venue_order_id: Option<VenueOrderId>,
        client_order_id: Option<ClientOrderId>,
    ) -> anyhow::Result<Option<OrderStatusReport>> {
        anyhow::ensure!(
            venue_order_id.is_some() || client_order_id.is_some(),
            "Either venue_order_id or client_order_id must be provided"
        );

        let symbol = instrument_id.symbol.inner();
        let instrument = self.instrument_from_cache(symbol)?;
        let ts_init = self.generate_ts_init();

        let order_id = venue_order_id
            .map(|id| id.inner().parse::<i64>())
            .transpose()
            .map_err(|_| anyhow::anyhow!("Invalid venue order ID"))?;

        let client_id_str =
            client_order_id.map(|id| encode_broker_id(&id, BINANCE_NAUTILUS_SPOT_BROKER_ID));

        let order = match self
            .inner
            .query_order(symbol.as_str(), order_id, client_id_str.as_deref())
            .await
        {
            Ok(order) => order,
            Err(e) if Self::is_no_such_order_error(&e) => {
                log::debug!("Binance Spot order not found: instrument_id={instrument_id}");
                return Ok(None);
            }
            Err(e) => anyhow::bail!(e),
        };

        parse_order_status_report_sbe(

View on GitHub (pinned to 18893faf8b)

Solutions

1. Verify the VenueOrderId contains the numeric Binance orderId returned by place_order/cancel_order (response.order_id), not a client order ID.
2. Trim whitespace and ensure the ID string contains only digits before constructing the VenueOrderId.
3. If only a ClientOrderId is available, look it up first (e.g. via order cache or open_orders) to resolve the numeric venue order ID.
4. Check the ID fits in i64; Binance IDs are 64-bit but confirm the string was not truncated or padded in upstream storage.

Example fix

// before
let venue_id = VenueOrderId::new("BTCUSDT_12345"); // symbol-prefixed, not numeric
client.query_order(instrument_id, Some(venue_id), None).await?;
// after
let venue_id = VenueOrderId::new("1234567890"); // numeric Binance orderId
assert!(venue_id.inner().parse::<i64>().is_ok());
client.query_order(instrument_id, Some(venue_id), None).await?;

fn is_valid_venue_order_id(id: &VenueOrderId) -> bool {
    id.inner().trim().parse::<i64>().map(|v| v > 0).unwrap_or(false)
}
// call only if is_valid_venue_order_id(&id)

fn valid_venue_order_id(id: &VenueOrderId) -> Option<i64> {
    id.inner().parse::<i64>().ok().filter(|v| *v > 0)
}

match client.query_order(instrument_id, Some(venue_id), None).await {
    Ok(order) => { /* ... */ }
    Err(e) if e.to_string().contains("Invalid venue order ID") => {
        log::warn!("non-numeric venue order id: {venue_id}");
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: Calling query_order (or any method passing venue_order_id to it) with a VenueOrderId whose inner string is empty, non-numeric (e.g. a client-generated ID or UUID), negative, or exceeds the i64 range (e.g. >9223372036854775807).

Common situations: Passing a Nautilus ClientOrderId where a VenueOrderId is expected; using a venue order ID copied from a different exchange; formatting artifacts such as whitespace or quotes around the numeric ID; ID strings sourced from logs or third-party tools.

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

• unrecognized side '{side}'
• quantity size={} cannot be represented with precision={}
• Gamma {scope} filter '{key}' must be true or false, was '{va
• Gamma {scope} filter '{key}' must contain non-empty comma-se
• Gamma {scope} filter '{key}' cannot be empty

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