nautechsystems/nautilus_trader · error
Order quantity is not exactly representable in base token…
Error message
Order quantity {quantity} is not exactly representable in {decimals} base token decimals What it means
When the quantity's raw precision exceeds the token's decimals, the raw amount must be divisible by 10^(raw_precision - decimals) to map exactly onto token units. If not, the conversion would require rounding, which is rejected to preserve exact discrete values, and this error names the offending quantity and decimals.
Solutions
- Round the order quantity down to a value representable in the token's decimals before conversion
- Correct the instrument definition so its size precision does not exceed the token's decimals
- Fix upstream sizing math to quantize to the token's decimal grid
- Verify the token decimals value passed in matches the actual contract
Example fix
// before: passing raw computed size let qty = Quantity::new(notional / price, 9); let raw = quantity_to_raw_amount(qty, decimals)?; // after: quantize to token decimals first let step = 10f64.powi(-(decimals as i32)); let qty = Quantity::new((notional / price).floor_to(step), decimals as u8); let raw = quantity_to_raw_amount(qty, decimals)?;
Defensive patterns
Strategy: validation
Validate before calling
fn is_representable(raw: &U256, raw_precision: u8, decimals: u8) -> bool {
if decimals >= raw_precision { return true; }
let div = U256::from(10u64).pow(U256::from(raw_precision - decimals));
(raw % div).is_zero()
} Try / catch
match res {
Err(e) if e.to_string().contains("not exactly representable") => {
let qty = quantize_to_decimals(quantity, decimals);
quantity_to_raw_amount(qty, decimals)?
}
other => other?,
} Prevention
- Configure instrument size precision no finer than the token's decimals
- Quantize quantities to the token decimal grid before conversion
- Keep precision definitions in sync with the actual token contract
- Test conversions across precision/decimal combinations
When it happens
Trigger: Converting an order Quantity whose raw value has sub-base-unit precision (e.g. raw precision 9 with a token using 6 decimals) where quantity.raw is not divisible by 10^(raw_precision - decimals) — e.g. quantity 1.0000005 on a 6-decimal token.
Common situations: Instrument price/size precision configured finer than the token's decimals; quantities generated from USD-notional math at higher precision; a mismatch between the instrument definition's precision and the actual token contract decimals.
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
- invalid quantity
- quantity ` ` rounds to 0 ticks at size_precision
- quantity size= cannot be represented with precision=
- size decimals exceeds maximum
- size precision exceeds maximum
AI-assisted analysis of nautechsystems/nautilus_trader@18893faf8b (2026-09-08).
Data as JSON: /api/errors/d990b3d6e2504438.
Report an issue: GitHub.
Appendix: source
Thrown at crates/adapters/blockchain/src/execution/client.rs:5220
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,
) -> anyhow::Result<(Address, Address)> {
match side {
OrderSide::Sell => Ok((base, quote)),
OrderSide::Buy => Ok((quote, base)),
}
}
View on GitHub (pinned to 18893faf8b)