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
- Check that pool.fee is in the correct units (Uniswap fee tiers like 500/3000/10000); fix the metadata source/parsing
- Correct any manually configured pool fee values so they are < 16,777,216
- 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
- Store fee tiers in native Uniswap units (500/3000/10000)
- Validate pool metadata at ingestion time, not at swap time
- Beware of basis-point vs raw-fee unit confusion from upstream APIs
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
- Pool has no fee tier
- Derived minimum output is zero for quoted output
- Executed amount scaling overflow
- Finalized block timestamp overflows nanoseconds
- Finalized Swap side does not match Sell order
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(
"e_token.symbol,
quote_token.decimals,
0,
"e_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)