nautechsystems/nautilus_trader · error

Binance user trade ID overflow during pagination

Error message

Binance user trade ID overflow during pagination

What it means

The ID-based pagination path advances its cursor with `max_trade_id.checked_add(1)`. Binance trade IDs are i64; if the maximum ID on a page is i64::MAX the increment overflows, and `checked_add` returns None, producing this contextual error instead of a silent wraparound to a negative cursor.

Source

Thrown at crates/adapters/binance/src/futures/execution.rs:2563

                let page_len = page.len();
                let max_trade_id = page.iter().map(|trade| trade.id).max().unwrap();
                let passed_end = requested_end_time
                    .is_some_and(|end_time| page.iter().any(|trade| trade.time > end_time));

                trades.extend(page.into_iter().filter(|trade| {
                    requested_end_time.is_none_or(|end_time| trade.time <= end_time)
                        && seen_trade_ids.insert(trade.id)
                }));

                if page_len < USER_TRADES_PAGE_LIMIT as usize || passed_end {
                    break;
                }

                let next_from_id = max_trade_id
                    .checked_add(1)
                    .context("Binance user trade ID overflow during pagination")?;
                anyhow::ensure!(
                    next_from_id > from_id,
                    "Binance user-trades pagination made no progress"
                );
                from_id = next_from_id;
            }
        }

        trades.sort_unstable_by_key(|trade| (trade.time, trade.id));
        let ts_init = self.clock.get_time_ns();

        let mut reports = Vec::new();

        for trade in trades {
            let venue_position_id = make_venue_position_id(
                self.config.use_position_ids,
                instrument.id(),
                trade.position_side,
            )?;

View on GitHub (pinned to 18893faf8b)

Solutions

1. If in tests, use realistic trade IDs well below i64::MAX in fixtures.
2. If hit in production, report/patch the adapter to use u64 or saturating arithmetic for the cursor.
3. Restart reconciliation after the problematic range so pagination starts from a lower cursor.

Example fix

// before
let next_from_id = max_trade_id.checked_add(1).context("Binance user trade ID overflow during pagination")?;
// after (adapter-side patch)
let next_from_id = max_trade_id.saturating_add(1); // and break when saturated

if let Err(e) = client.generate_mass_status().await {
    if e.to_string().contains("ID overflow") {
        error!("Binance trade ID overflow — adapter patch required");
    } else {
        return Err(e);
    }
}

When it happens

Trigger: generate_fill_reports pagination receiving a page whose maximum Binance trade id equals i64::MAX (9223372036854775807), making cursor+1 unrepresentable.

Common situations: Essentially only with adversarial/mocked data or a hypothetical future where Binance IDs reach i64::MAX; real Binance trade IDs are far below this bound. Mostly seen in unit tests with fabricated IDs.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Binance {field} timestamp is outside the UnixNanos range: {v
• Binance user-trades pagination made no progress
• order-book level index overflow
• invalid negative kline trade count {}
• invalid cumulative_quote_qty='{}' for cumulative_filled_qty=

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