nautechsystems/nautilus_trader · error

Executed amount scaling overflow

Error message

Executed amount scaling overflow

What it means

When mapping an executed (filled) raw on-chain amount back to a Quantity, if token decimals exceed FIXED_PRECISION the client divides by 10^(decimals - FIXED_PRECISION). This error is thrown when that scale power overflows U256, so the executed amount cannot be reduced to fixed precision.

Source

Thrown at crates/adapters/blockchain/src/execution/client.rs:5256

fn fill_price_from_quote(
    last_qty: Quantity,
    quote_amount: U256,
    quote_currency: Currency,
) -> anyhow::Result<Price> {
    let quote = Money::from_u256(quote_amount, quote_currency)?;
    Price::from_decimal_dp(quote.as_decimal() / last_qty.as_decimal(), FIXED_PRECISION)
        .map_err(anyhow::Error::from)
}

fn raw_amount_to_quantity(amount: U256, decimals: u8) -> anyhow::Result<Quantity> {
    if amount.is_zero() {
        anyhow::bail!("Executed amount must be positive");
    }
    let quantity = if decimals >= FIXED_PRECISION {
        let scale = U256::from(10u64)
            .checked_pow(U256::from(decimals - FIXED_PRECISION))
            .ok_or_else(|| anyhow::anyhow!("Executed amount scaling overflow"))?;
        Quantity::from_u256(amount / scale, FIXED_PRECISION).map_err(anyhow::Error::from)?
    } else {
        Quantity::from_u256(amount, decimals).map_err(anyhow::Error::from)?
    };

    if quantity.is_zero() {
        anyhow::bail!(
            "Executed amount {amount} is below representable quantity precision {FIXED_PRECISION}"
        );
    }
    Ok(quantity)
}

fn exact_output_amount(quote: &SwapQuote, zero_for_one: bool) -> anyhow::Result<U256> {
    let amount = if zero_for_one {
        quote.amount1
    } else {
        quote.amount0

View on GitHub (pinned to 18893faf8b)

Solutions

1. Correct the token decimals in the instrument/chain metadata to the contract's actual value
2. Skip or quarantine executions for tokens with implausible decimals until metadata is verified
3. Validate decimals bounds when registering the token with the execution client

fn assert_exec_amount_decodable(decimals: u32) -> Result<(), String> {
    if decimals.saturating_sub(FIXED_PRECISION) > 78 {
        Err(format!("decimals {decimals} too large to reduce executed amount".into()))
    } else { Ok(()) }
}

match result {
    Err(e) if e.to_string().contains("Executed amount scaling overflow") => { /* quarantine token, fix metadata */ }
    other => other?,
}

When it happens

Trigger: Processing a fill/execution event for a token whose decimals - FIXED_PRECISION exponent makes 10^(decimals - FIXED_PRECISION) exceed U256::MAX (implausibly large decimals on the token metadata).

Common situations: Reconciling execution reports for a token with misreported decimals; indexing events from an unvetted token contract with corrupt 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

• {type_name} amount {amount} overflows U256 while scaling fro
• Order amount scaling overflow
• Order amount overflow scaling quantity to raw token units
• WETH balance overflow for included transaction {tx_hash} at
• {type_name} raw value overflows U256 while rounding half to

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