nautechsystems/nautilus_trader · error

{type_name} amount {amount} overflows U256 while scaling fro

Error message

{type_name} amount {amount} overflows U256 while scaling from {decimals} to {fixed_precision} decimals

What it means

This error is raised by scale_u256_to_raw when multiplying a U256 amount by the scaling factor 10^(fixed_precision - decimals) would exceed the U256 maximum. It means the raw integer value of the amount cannot be represented in U256 after upscaling from the token's decimals to the fixed precision used by the system. The library throws it via checked_mul to avoid silent wrapping arithmetic in blockchain value conversion.

Source

Thrown at crates/adapters/blockchain/src/decode.rs:106

fn scale_u256_to_raw(
    amount: U256,
    decimals: u8,
    fixed_precision: u8,
    raw_max: U256,
    type_name: &str,
    raw_max_name: &str,
) -> anyhow::Result<U256> {
    let raw = if decimals < fixed_precision {
        let scale = U256::from(10)
            .checked_pow(U256::from(fixed_precision - decimals))
            .ok_or_else(|| {
                anyhow::anyhow!(
                    "Scale 10^{} exceeds U256 while converting {type_name}",
                    fixed_precision - decimals
                )
            })?;
        amount.checked_mul(scale).ok_or_else(|| {
            anyhow::anyhow!(
                "{type_name} amount {amount} overflows U256 while scaling from {decimals} to {fixed_precision} decimals"
            )
        })?
    } else if decimals > fixed_precision {
        round_u256_half_even(amount, decimals - fixed_precision, type_name)?
    } else {
        amount
    };

    check_raw_range(raw, raw_max, type_name, raw_max_name)?;
    Ok(raw)
}

fn check_raw_range(
    raw: U256,
    raw_max: U256,
    type_name: &str,
    raw_max_name: &str,

View on GitHub (pinned to 18893faf8b)

Solutions

1. Lower the configured fixed_precision so the required scaling factor 10^(fixed_precision - decimals) fits in U256 for your value range
2. Check the source event/decimals value: a near-max U256 amount usually indicates a corrupted or adversarial log entry; skip or reject the record
3. If the token's decimals metadata is wrong (too low), fix the decimals source so no upscaling is attempted
4. If you genuinely need larger values, reconsider the representation — U256 cannot be widened; use a big-integer type outside this API

Example fix

// before
let qty = u256_to_quantity(amount, decimals, fixed_precision, type_name)?; // fixed_precision = 36
// after
let qty = u256_to_quantity(amount, decimals, 18, type_name)?; // smaller scale avoids overflow

fn can_scale(amount: U256, decimals: u32, fixed_precision: u32) -> bool {
    if decimals >= fixed_precision { return true; }
    let scale = U256::from(10).pow(U256::from(fixed_precision - decimals));
    amount.checked_mul(scale).is_some()
}

match u256_to_quantity(amount, decimals, fixed_precision, "Token") {
    Ok(q) => use(q),
    Err(e) if e.to_string().contains("overflows U256") => reject_record(e),
    Err(e) => return Err(e),
}

When it happens

Trigger: Calling u256_to_quantity or u256_to_price (both funnel through scale_u256_to_raw) with a U256 amount that is already near 2^256 and a target fixed_precision greater than the token's decimals, so the multiply by 10^(fixed_precision-decimals) overflows. Also hit directly by tests with extreme amount/precision combinations.

Common situations: Indexing a token with very high decimals plus a fixed_precision configured too high; a malformed or adversarial contract event emitting a near-maximum uint256 amount; incorrectly configured fixed_precision in adapter config.

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

• Order amount scaling overflow
• Order amount overflow scaling quantity to raw token units
• Executed amount scaling overflow
• 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/47585ca6ea9a3bda. Report an issue: GitHub.