nautechsystems/nautilus_trader · error
Order amount scaling overflow
Error message
Order amount scaling overflow
What it means
When converting an order Quantity to raw token units, the client raises 10^(decimals - raw_precision) and multiplies the fixed-precision raw value. This error is thrown when the scaling power itself (10^exponent) overflows U256, meaning the decimal delta between the order precision and the token decimals is too large to represent.
Solutions
- Verify the token's decimals value matches the on-chain contract (call decimals() on the token) and fix the instrument/provider config
- Ensure quantity.precision (or FIXED_PRECISION fallback) is set correctly for the instrument so decimals - raw_precision stays small
- Cap or sanitize decimals before calling the conversion; reject tokens with implausible decimals values upstream
Example fix
// before
let scale = U256::from(10u64).checked_pow(U256::from(decimals - raw_precision))?;
// after
let exponent = (decimals - raw_precision) as u32;
if exponent > 78 { anyhow::bail!("decimals delta {exponent} too large for U256 scaling"); }
let scale = U256::from(10u64).checked_pow(U256::from(exponent))?; Defensive patterns
Strategy: validation
Validate before calling
fn assert_scalable(quantity_precision: u32, decimals: u32) -> Result<(), String> {
let delta = decimals.abs_diff(quantity_precision.max(FIXED_PRECISION));
if delta > 78 { Err(format!("decimals delta {delta} cannot be scaled in U256")) } else { Ok(()) }
} Try / catch
match client.submit_order(...) {
Err(e) if e.to_string().contains("Order amount scaling overflow") => { /* fix decimals config / reject order */ }
other => other?,
} Prevention
- Load token decimals from the on-chain contract, never hardcode
- Validate decimals is in a plausible range (0..=78) at instrument registration
- Log the precision delta between instrument and token when it exceeds a threshold
When it happens
Trigger: Calling the execution client to submit an order whose instrument quantity precision differs from the token's decimals by an exponent so large that 10^(decimals - raw_precision) exceeds U256::MAX (e.g. absurd decimals values or a token with astronomically many decimals).
Common situations: Misconfigured instrument definitions where token decimals were read from the wrong contract or hardcoded incorrectly; a corrupted/malicious token metadata feed reporting decimals in the hundreds; copy-paste decimals from a different chain's token.
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 overflow scaling quantity to raw token units
- 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/e5e5a29159795e34.
Report an issue: GitHub.
Appendix: source
Thrown at crates/adapters/blockchain/src/execution/client.rs:5211
}
/// 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,View on GitHub (pinned to 18893faf8b)