nautechsystems/nautilus_trader · error

Pool fee exceeds uint24

Error message

Pool {instrument_id} fee {fee} exceeds uint24

What it means

prepare_swap found the pool's fee tier exceeds the u24 maximum when converting to U24; pools are keyed by a uint24 fee parameter, so a fee outside that range cannot represent a valid pool and the conversion fails.

Solutions

  1. Check that pool.fee is in the correct units (Uniswap fee tiers like 500/3000/10000); fix the metadata source/parsing
  2. Correct any manually configured pool fee values so they are < 16,777,216
  3. Re-fetch pool metadata from the chain to replace corrupt cached values

Example fix

// before
fee: 30_000_000, // exceeds uint24
// after
fee: 3_000, // valid Uniswap V3 tier
Defensive patterns

Strategy: validation

Validate before calling

let fee = pool.fee.expect("fee tier missing");
if fee >= (1u64 << 24) {
    return Err(format!("fee {fee} exceeds uint24; check fee units"));
}

Type guard

fn valid_fee(fee: u64) -> Option<U24> {
    U24::try_from(fee).ok()
}

Try / catch

match client.submit_order(order).await {
    Err(e) if e.to_string().contains("exceeds uint24") => {
        // fix pool metadata source/units, refetch, retry
        reload_pool_metadata(&instrument_id).await?;
        client.submit_order(order).await
    }
    r => r,
}

Prevention

When it happens

Trigger: `prepare_swap()` gets `pool.fee = Some(fee)` where fee >= 2^24 (16,777,216) and `U24::try_from(fee)` fails.

Common situations: Corrupt or malformed pool metadata (fee parsed from wrong field/units, e.g. raw integer vs basis points); misconfigured custom pool definition with an out-of-range fee; upstream API change in fee representation.

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


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

Appendix: source

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

        if !matches!(order.order_side(), OrderSide::Buy | OrderSide::Sell) {
            anyhow::bail!(
                "Unsupported order side {}; only Buy and Sell are supported",
                order.order_side()
            );
        }

        if order.is_quote_quantity() {
            anyhow::bail!(
                "Quote-denominated quantities are not supported; quantity must be denominated in the base token"
            );
        }

        let fee = pool
            .fee
            .ok_or_else(|| anyhow::anyhow!("Pool {instrument_id} has no fee tier"))?;
        let fee = U24::try_from(fee)
            .map_err(|_| anyhow::anyhow!("Pool {instrument_id} fee {fee} exceeds uint24"))?;

        let base_token = pool.get_base_token();
        let quote_token = pool.get_quote_token();
        let quote_currency = Currency::new_checked(
            &quote_token.symbol,
            quote_token.decimals,
            0,
            &quote_token.name,
            CurrencyType::Crypto,
        )?;
        let (token_in, token_out) =
            swap_token_pair(order.order_side(), base_token.address, quote_token.address)?;

        if !self
            .transaction_limits
            .allowed_token_pairs
            .contains(&(token_in, token_out))
        {

View on GitHub (pinned to 18893faf8b)