nautechsystems/nautilus_trader · error

Inverted price exceeds U256 range

Error message

Inverted price exceeds U256 range

What it means

After dividing numerator by price_square in the inverted branch (decimal_diff < 0), the resulting quotient must fit into a U256 to become the raw fixed-point price. This error is thrown when the computed inverted price exceeds U256 range, indicating a price so large it cannot be represented by the library's fixed-point Price type.

Source

Thrown at crates/model/src/defi/tick_map/sqrt_price_math.rs:426

                        .checked_mul(decimal_adjustment)
                        .ok_or_else(|| {
                            anyhow::anyhow!("Inverted price denominator exceeds U256 range")
                        })?;
                FullMath::mul_div(numerator, U256::from(1), denominator)?
            }
        } else {
            let price_square: U512 = sqrt_price.widening_mul(sqrt_price);
            anyhow::ensure!(
                !price_square.is_zero(),
                "Cannot decode inverted price from zero sqrt_price_x96"
            );
            let numerator = U512::from(divisor_base)
                .checked_mul(U512::from(decimal_adjustment))
                .and_then(|value| value.checked_mul(U512::from(fixed_scalar)))
                .ok_or_else(|| anyhow::anyhow!("Inverted price numerator exceeds U512 range"))?;
            let quotient = numerator / price_square;
            U256::checked_from_limbs_slice(quotient.as_limbs())
                .ok_or_else(|| anyhow::anyhow!("Inverted price exceeds U256 range"))?
        }
    } else if decimal_diff >= 0 {
        FullMath::mul_div_scaled(
            sqrt_price,
            sqrt_price,
            divisor_base,
            &[fixed_scalar, decimal_adjustment],
        )?
    } else {
        FullMath::mul_div_scaled(sqrt_price, sqrt_price, divisor_base, &[fixed_scalar])?
            / decimal_adjustment
    };

    price_from_u256(price_raw)
}

pub(crate) fn price_from_u256(price_raw: U256) -> anyhow::Result<Price> {
    anyhow::ensure!(

View on GitHub (pinned to 18893faf8b)

Solutions

1. Sanity-check sqrt_price_x96 magnitude before decoding; extremely small values with big decimal gaps produce unusable prices.
2. Use the non-inverted orientation (invert=false) and invert at a higher level where the small price is representable.
3. Clamp or reject prices exceeding PRICE_RAW_MAX at the caller after catching the error.

Example fix

// before
let price = decode_sqrt_price_x96_to_price_tokens_adjusted(sqrt_price_x96, 0, 18, true)?;
// after
let price = match decode_sqrt_price_x96_to_price_tokens_adjusted(sqrt_price_x96, 0, 18, true) {
    Ok(p) => p,
    Err(_) => return Ok(Price::max(FIXED_PRECISION)), // or skip pool
};

fn quotient_may_exceed_u256(sqrt_price_x96: U160, d0: u8, d1: u8) -> bool {
    // tiny sqrt price with large decimal gap can overflow the inverted quotient
    sqrt_price_x96 < U160::from(1000u32) && i32::from(d1) > i32::from(d0)
}

let price = decode_sqrt_price_x96_to_price_tokens_adjusted(sp, d0, d1, true)
    .ok()
    .unwrap_or_else(|| Price::max(FIXED_PRECISION)); // saturate instead of failing

When it happens

Trigger: Calling decode_sqrt_price_x96_to_price_tokens_adjusted with invert=true and token0_decimals < token1_decimals when sqrt_price_x96^2 is very small relative to numerator (tiny sqrt price with a large decimal adjustment), yielding a quotient > U256::MAX.

Common situations: Decoding a near-zero sqrt_price_x96 for a pool with a large decimal gap (e.g. token0 with 0 decimals, token1 with 18) — the inverted price token0/token1 becomes astronomically large.

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

• Inverted price numerator exceeds U512 range
• Cannot quote swap with zero amount
• Price limit must be less than current price for zero_for_one
• Price limit must be greater than current price for one_for_z
• No liquidity

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