nautechsystems/nautilus_trader · error
Order amount overflow scaling quantity to raw token units
Error message
Order amount overflow scaling quantity to raw token units
What it means
After scaling an order quantity up to raw token units, the client multiplies the raw U256 value by 10^(decimals - raw_precision). This error is thrown when that multiplication overflows U256, i.e. the quantity is too large to express in base token units.
Solutions
- Reduce the order quantity to a value representable in raw token units
- Verify token decimals against the on-chain contract and correct the instrument config
- Add a pre-trade sanity check that quantity scaled fits within U256 and reject oversized orders before submission
Example fix
// before
raw.checked_mul(scale).ok_or_else(|| anyhow::anyhow!("Order amount overflow scaling quantity to raw token units"))
// after
let max_raw = U256::MAX / scale;
if raw > max_raw { anyhow::bail!("quantity {} exceeds raw token capacity", quantity); }
raw.checked_mul(scale).ok_or_else(|| anyhow::anyhow!("Order amount overflow scaling quantity to raw token units")) Defensive patterns
Strategy: validation
Validate before calling
fn assert_order_size(quantity_raw: U256, scale: U256) -> Result<(), String> {
if quantity_raw > U256::MAX / scale { Err("order quantity exceeds raw token capacity".into()) } else { Ok(()) }
} Try / catch
match client.submit_order(...) {
Err(e) if e.to_string().contains("Order amount overflow scaling quantity") => { /* halve size / re-check decimals */ }
other => other?,
} Prevention
- Add a max-notional/max-size pre-trade risk check
- Verify token decimals against the chain before trading
- Sanity-check order sizes against the token's total supply
When it happens
Trigger: Submitting an order whose quantity, once scaled by the token decimal delta, exceeds U256::MAX — e.g. a quantity at fixed precision near 2^256/10^k with decimals > raw_precision.
Common situations: Order size typo (e.g. entering 1,000,000,000 instead of 1.0); wrongly configured token decimals inflating the scale factor; trading a meme token with huge supply and large configured decimals.
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
- Executed amount scaling overflow
- Order amount scaling overflow
- amount overflows U256 while scaling from to decimals
- Minimum output derivation overflow
- raw value overflows U256 while rounding half to even
AI-assisted analysis of nautechsystems/nautilus_trader@18893faf8b (2026-09-08).
Data as JSON: /api/errors/a760ea030f3e2364.
Report an issue: GitHub.
Appendix: source
Thrown at crates/adapters/blockchain/src/execution/client.rs:5213
/// Converts a base-denominated order quantity into raw token units with exact integer
/// scaling by the base token decimals.
///
/// `Quantity::raw` is scaled to the greater of its declared precision and `FIXED_PRECISION`;
/// token amounts are scaled to the token's decimals. Quantities not exactly representable in
/// token units are rejected rather than rounded.
fn quantity_to_raw_amount(quantity: Quantity, decimals: u8) -> anyhow::Result<U256> {
if quantity.is_zero() {
anyhow::bail!("Order quantity must be positive");
}
let raw = U256::from(quantity.raw);
let raw_precision = quantity.precision.max(FIXED_PRECISION);
if decimals >= raw_precision {
let scale = U256::from(10u64)
.checked_pow(U256::from(decimals - raw_precision))
.ok_or_else(|| anyhow::anyhow!("Order amount scaling overflow"))?;
raw.checked_mul(scale).ok_or_else(|| {
anyhow::anyhow!("Order amount overflow scaling quantity to raw token units")
})
} else {
let divisor = U256::from(10u64)
.checked_pow(U256::from(raw_precision - decimals))
.ok_or_else(|| anyhow::anyhow!("Order amount scaling overflow"))?;
if !(raw % divisor).is_zero() {
anyhow::bail!(
"Order quantity {quantity} is not exactly representable in {decimals} base token decimals"
);
}
Ok(raw / divisor)
}
}
fn swap_token_pair(
side: OrderSide,
base: Address,
quote: Address,View on GitHub (pinned to 18893faf8b)