{"record":{"id":"58d3e22c6990622d","repo":"nautechsystems/nautilus_trader","slug":"failed-to-parse-hex-quantity-s-e","errorCode":null,"errorMessage":"Failed to parse hex quantity '{s}': {e}","messagePattern":"Failed to parse hex quantity '(.+?)': (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/adapters/blockchain/src/rpc/types.rs","lineNumber":263,"sourceCode":"\nfn deserialize_hex_bool<'de, D>(deserializer: D) -> Result<bool, D::Error>\nwhere\n    D: serde::Deserializer<'de>,\n{\n    let s = String::deserialize(deserializer)?;\n    match s.as_str() {\n        \"0x0\" => Ok(false),\n        \"0x1\" => Ok(true),\n        _ => Err(serde::de::Error::custom(\n            \"invalid transaction receipt status; expected 0x0 or 0x1\",\n        )),\n    }\n}\n\nfn parse_hex_quantity(s: &str) -> anyhow::Result<u128> {\n    let stripped = s.strip_prefix(\"0x\").unwrap_or(s);\n    u128::from_str_radix(stripped, 16)\n        .map_err(|e| anyhow::anyhow!(\"Failed to parse hex quantity '{s}': {e}\"))\n}\n","sourceCodeStart":245,"sourceCodeEnd":265,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/18893faf8b356be3320add8de2f861b0b647cf06/crates/adapters/blockchain/src/rpc/types.rs#L245-L265","documentation":"parse_hex_quantity converts a hex quantity string (EVM 'QUANTITY' encoding, e.g. \"0x1a\") into a u128. It strips an optional 0x prefix and parses with u128::from_str_radix; any parse failure (bad characters, empty string, value exceeding u128) is wrapped in this error including the original string and the inner ParseIntError.","triggerScenarios":"Any deserialize_hex_u64/deserialize_hex_u64_opt/deserialize_hex_u8_opt/deserialize_hex_u128_opt invocation (serde field deserialization of RPC JSON responses) where the field is not a valid hex quantity: contains non-hex characters, is an empty string, uses decimal notation, or the value overflows the target type after conversion.","commonSituations":"An RPC node returns a decimal string or JSON number instead of a 0x-prefixed hex quantity; a field contains '0x' alone or 'pending'/'latest' tags passed to a quantity field; upstream API changed response format after a version update; value too large for u64/u8 target after a successful u128 parse.","solutions":["Inspect the '{s}' value in the message; confirm it is a clean hex string (optional 0x prefix, only [0-9a-fA-F]).","If the source sends decimals or JSON numbers, convert to hex upstream or wrap the field with a tolerant deserializer before it reaches these functions.","For tag values like 'latest'/'pending', resolve them to a quantity first or use a tag-aware deserializer; this parser only accepts numeric hex.","If the message shows an overflow-style ParseIntError for a valid hex string, the value exceeds the target width (u64/u8/u128); use the wider deserializer variant."],"exampleFix":"// before (server sends decimal string)\n{\"blockNumber\": \"12345\"}\n// after (EVM hex quantity)\n{\"blockNumber\": \"0x3039\"}","handlingStrategy":"validation","validationCode":"fn is_hex_quantity(s: &str) -> bool {\n    let h = s.strip_prefix(\"0x\").unwrap_or(s);\n    !h.is_empty() && h.chars().all(|c| c.is_ascii_hexdigit()) && h.chars().count() <= 32\n}","typeGuard":null,"tryCatchPattern":"match parse_hex_quantity(field) {\n    Ok(v) => { /* use v */ }\n    Err(e) => { eprintln!(\"bad quantity field: {e}\"); /* treat as null/default */ }\n}","preventionTips":["Ensure your RPC provider returns EVM QUANTITY encoding (0x-prefixed hex) for numeric fields.","Handle block tags ('latest', 'pending') separately from quantities.","Use u128-safe deserialization for values that may exceed u64 (e.g. gas, balances).","Pin and test against the provider's API version to catch format changes early."],"tags":["parsing","hex","serialization","blockchain"],"backgroundTag":"invalid-argument-format","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"}