{"record":{"id":"d2e6e106e6e96374","repo":"nautechsystems/nautilus_trader","slug":"executed-amount-amount-is-below-representable-qu","errorCode":null,"errorMessage":"Executed amount {amount} is below representable quantity precision {FIXED_PRECISION}","messagePattern":"Executed amount (.+?) is below representable quantity precision (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"crates/adapters/blockchain/src/execution/client.rs","lineNumber":5263,"sourceCode":"    Price::from_decimal_dp(quote.as_decimal() / last_qty.as_decimal(), FIXED_PRECISION)\n        .map_err(anyhow::Error::from)\n}\n\nfn raw_amount_to_quantity(amount: U256, decimals: u8) -> anyhow::Result<Quantity> {\n    if amount.is_zero() {\n        anyhow::bail!(\"Executed amount must be positive\");\n    }\n    let quantity = if decimals >= FIXED_PRECISION {\n        let scale = U256::from(10u64)\n            .checked_pow(U256::from(decimals - FIXED_PRECISION))\n            .ok_or_else(|| anyhow::anyhow!(\"Executed amount scaling overflow\"))?;\n        Quantity::from_u256(amount / scale, FIXED_PRECISION).map_err(anyhow::Error::from)?\n    } else {\n        Quantity::from_u256(amount, decimals).map_err(anyhow::Error::from)?\n    };\n\n    if quantity.is_zero() {\n        anyhow::bail!(\n            \"Executed amount {amount} is below representable quantity precision {FIXED_PRECISION}\"\n        );\n    }\n    Ok(quantity)\n}\n\nfn exact_output_amount(quote: &SwapQuote, zero_for_one: bool) -> anyhow::Result<U256> {\n    let amount = if zero_for_one {\n        quote.amount1\n    } else {\n        quote.amount0\n    };\n\n    if !amount.is_negative() {\n        anyhow::bail!(\"Swap quote output amount {amount} is not a positive output\");\n    }\n    Ok(amount.unsigned_abs())\n}","sourceCodeStart":5245,"sourceCodeEnd":5281,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/18893faf8b356be3320add8de2f861b0b647cf06/crates/adapters/blockchain/src/execution/client.rs#L5245-L5281","documentation":"After scaling the raw U256 amount into a Quantity, the adapter checks the result is nonzero. If the raw amount is smaller than one unit of the representable fixed-point precision (FIXED_PRECISION), the quantity truncates to zero and the adapter bails rather than propagate a zero executed quantity.","triggerScenarios":"raw_amount_to_quantity receives a tiny raw amount (e.g. 1..scale-1 wei) with token decimals >= FIXED_PRECISION, so amount/scale rounds to zero.","commonSituations":"Dust fills/swaps on high-decimals tokens; token decimals misconfigured so scale is much larger than expected.","solutions":["Verify the token decimals configured match the actual on-chain token","Treat the execution as dust: skip it rather than erroring, or accumulate amounts before converting","If the fill is real and important, check for a decimals/parsing bug upstream"],"exampleFix":"// before\nlet qty = raw_amount_to_quantity(amount, decimals)?;\n// after\nif amount < U256::from(10u64).pow(decimals.into()) {\n    tracing::warn!(\"dust execution {} below precision, skipping\", amount);\n    return Ok(None);\n}\nlet qty = raw_amount_to_quantity(amount, decimals)?;","handlingStrategy":"validation","validationCode":"let scale = U256::from(10u64).pow(U256::from(decimals));\nif amount < scale {\n    tracing::warn!(\"amount {amount} below 1 unit at {decimals} decimals; treating as dust\");\n    return Ok(None);\n}","typeGuard":null,"tryCatchPattern":"match raw_amount_to_quantity(amount, decimals) {\n    Ok(q) => handle(q),\n    Err(e) if e.to_string().contains(\"below representable\") => handle_dust(amount),\n    Err(e) => return Err(e),\n}","preventionTips":["Confirm token decimals from the token contract, not hardcoded values","Handle dust explicitly (skip or batch) instead of letting it error"],"tags":["blockchain","precision","dust"],"backgroundTag":"value-out-of-range","analyzedSha":"18893faf8b356be3320add8de2f861b0b647cf06","analyzedAt":"2026-09-08T20:49:34.690Z","contentChangedAt":"2026-09-08T20:49:34.690Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}