nautechsystems/nautilus_trader · error · anyhow::Error

Binance historical bars require time aggregation

Error message

Binance historical bars require time aggregation

What it means

Binance klines are time-interval candles (1m, 5m, 1h, ...), so the Binance Futures data client requires the bar spec to be time-aggregated for historical requests. Tick-, volume-, and dollar-based aggregations are rejected in request_bars because the exchange cannot serve them.

Solutions

  1. Use a time-based step (SECOND, MINUTE, HOUR, DAY) in the bar spec, e.g. 'BTCUSDT-PERP.BINANCE-5-MINUTE-LAST-EXTERNAL'
  2. Download historical trades/ticks and aggregate into tick/volume bars internally in NautilusTrader
  3. Pre-compute custom bars offline and load them from a catalog instead of requesting from the adapter

Example fix

// before
let bar_type = BarType::from_str("BTCUSDT-PERP.BINANCE-1000-VOLUME-LAST-EXTERNAL")?;
// after
let bar_type = BarType::from_str("BTCUSDT-PERP.BINANCE-1-HOUR-LAST-EXTERNAL")?;
Defensive patterns

Strategy: validation

Validate before calling

let ok = bar_type.spec().is_time_aggregated();

Prevention

When it happens

Trigger: Requesting historical bars with a non-time aggregation in the spec, e.g. 'BTCUSDT-PERP.BINANCE-100-TICK-LAST-EXTERNAL' or '-1000-VOLUME-LAST-EXTERNAL'.

Common situations: Backtests requesting volume bars historically from Binance; volume/tick bars must instead be aggregated by Nautilus from downloaded trades/ticks.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors


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

Appendix: source

Thrown at crates/adapters/binance/src/futures/data.rs:3056

        let bar_type = request.bar_type;
        let start = request.start;
        let end = request.end;
        let limit = request.limit.map(|n| n.get() as u32);
        let request_id = request.request_id;
        let client_id = request.client_id.unwrap_or(self.client_id);
        let params = request.params;
        let clock = self.clock;
        let start_nanos = datetime_to_unix_nanos(start);
        let end_nanos = datetime_to_unix_nanos(end);
        anyhow::ensure!(
            bar_type.aggregation_source() == AggregationSource::External,
            "Binance historical bars require EXTERNAL aggregation"
        );
        anyhow::ensure!(
            bar_type.spec().price_type == PriceType::Last,
            "Binance historical bars require LAST price type"
        );
        anyhow::ensure!(
            bar_type.spec().is_time_aggregated(),
            "Binance historical bars require time aggregation"
        );

        self.spawn_command(async move {
            let result = http.request_bars(bar_type, start, end, limit).await;

            match result.context("failed to request bars from Binance Futures") {
                Ok(bars) => {
                    let response = DataResponse::Bars(BarsResponse::new(
                        request_id,
                        client_id,
                        bar_type,
                        bars,
                        start_nanos,
                        end_nanos,
                        clock.get_time_ns(),
                        params,

View on GitHub (pinned to 18893faf8b)