nautechsystems/nautilus_trader · error · anyhow::Error

Quote spend limit `max_amount` '{}' exceeds the U256 range

Error message

Quote spend limit `max_amount` '{}' exceeds the U256 range

What it means

Thrown in the `transaction_limits` processing of `BlockchainExecutionClient` when a quote spend limit's `max_amount` string parses as base-10 but represents a number larger than U256::MAX. Spend ceilings are parsed into `U256`; values beyond that cannot represent a valid token amount and are rejected.

Source

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

                );
            }

            if spend_token != token_in {
                anyhow::bail!(
                    "Quote spend limit for {token_in} -> {token_out} is denominated in {spend_token}; `spend_token` must match `token_in`"
                );
            }

            if limit.max_amount.is_empty()
                || !limit.max_amount.bytes().all(|byte| byte.is_ascii_digit())
            {
                anyhow::bail!(
                    "Quote spend limit `max_amount` '{}' must be a base-10 unsigned integer string",
                    limit.max_amount
                );
            }
            let max_amount = U256::from_str(&limit.max_amount).map_err(|_| {
                anyhow::anyhow!(
                    "Quote spend limit `max_amount` '{}' exceeds the U256 range",
                    limit.max_amount
                )
            })?;
            let ceiling = QuoteSpendCeiling {
                spend_token,
                spend_token_decimals: limit.spend_token_decimals,
                max_amount,
            };

            if parsed_quote_spend_limits
                .insert((token_in, token_out), ceiling)
                .is_some()
            {
                anyhow::bail!(
                    "Duplicate quote spend limit for token pair {token_in} -> {token_out}"
                );
            }

View on GitHub (pinned to 18893faf8b)

Solutions

1. Lower `max_amount` to a value within the U256 range (<= 2^256 - 1, and realistically <= total token supply).
2. Compute the base-10 value from a Decimal/human amount using the token's decimals instead of typing a raw integer.
3. If the intent was 'no limit', omit the limit entry rather than using a giant sentinel.

Example fix

// before (config)
[[limits]]
spend_token = "0x4200000000000000000000000000000000000006"
max_amount = "115792089237316195423570985008687907853269984665640564039457584007913129639936" # > U256::MAX
// after
max_amount = "115792089237316195423570985008687907853269984665640564039457584007913129639935" # <= U256::MAX (or an actual sane ceiling)

fn is_valid_u256_amount(s: &str) -> bool {
    s.chars().all(|c| c.is_ascii_digit())
        && !s.is_empty()
        && U256::from_str_radix(s, 10).is_ok()
}

match U256::from_str(&limit.max_amount) {
    Ok(v) => apply_ceiling(v),
    Err(_) if limit.max_amount.chars().all(|c| c.is_ascii_digit()) => {
        anyhow::bail!("max_amount {} exceeds U256 range; use a realistic spend ceiling", limit.max_amount);
    }
    Err(e) => return Err(e.into()),
}

When it happens

Trigger: Providing a quote spend limit config entry whose `max_amount` exceeds 2^256 - 1, e.g. an absurd value like 10^80, a placeholder string of many digits, or a misconfigured sentinel like "unlimited" spelled as a giant number.

Common situations: Hand-editing limits with a huge sentinel value; copy-pasting scientific notation expanded; generated config with an overflow default; mistyping decimals when converting from human-readable amounts.

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

• WETH balance overflow for included transaction {tx_hash} at
• request_rate_per_second must be greater than zero
• order_request_rate_per_second must be greater than zero
• heartbeat_secs must be positive when set
• heartbeat_timeout_secs must cover at least two server heartb

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