{"record":{"id":"cfffe06489bee64b","repo":"nautechsystems/nautilus_trader","slug":"invalid-negative-quantity-value","errorCode":null,"errorMessage":"Invalid negative quantity: {value}","messagePattern":"Invalid negative quantity: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/adapters/databento/src/decode/primitives.rs","lineNumber":328,"sourceCode":"\n/// Decodes a quantity from the given value, expressed in standard whole-number units.\n#[inline(always)]\n#[must_use]\npub fn decode_quantity(value: u64) -> Quantity {\n    quantity_from_whole(value)\n}\n\n/// Decodes a quantity from the given optional value, where `i64::MAX` indicates missing data.\n///\n/// # Errors\n///\n/// Returns an error if the quantity is negative.\n#[inline(always)]\npub fn decode_optional_quantity(value: i64) -> anyhow::Result<Option<Quantity>> {\n    match value {\n        i64::MAX => Ok(None),\n        value if value >= 0 => Ok(Some(quantity_from_whole(value as u64))),\n        value => anyhow::bail!(\"Invalid negative quantity: {value}\"),\n    }\n}\n\n/// Decodes a timestamp, returning an error if undefined.\n///\n/// Databento uses `u64::MAX` as `UNDEF_TIMESTAMP` sentinel for null timestamps.\n///\n/// # Errors\n///\n/// Returns an error if `value` is `u64::MAX` (undefined).\n#[inline(always)]\npub fn decode_timestamp(value: u64, field_name: &str) -> anyhow::Result<UnixNanos> {\n    if value == dbn::UNDEF_TIMESTAMP {\n        anyhow::bail!(\"Missing required timestamp for `{field_name}`\")\n    } else {\n        Ok(UnixNanos::from(value))\n    }\n}","sourceCodeStart":310,"sourceCodeEnd":346,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/18893faf8b356be3320add8de2f861b0b647cf06/crates/adapters/databento/src/decode/primitives.rs#L310-L346","documentation":"`decode_optional_quantity` converts an i64 Databento quantity into an `Option<Quantity>`: `i64::MAX` maps to `None` (undefined), non-negative values decode normally, and negative values are rejected because quantities in the Nautilus domain model can never be negative. The error surfaces when a Databento record carries a negative quantity that would corrupt downstream order/position logic.","triggerScenarios":"`decode_optional_quantity(v)` called with `v < 0` (and not `i64::MAX`); typically via `decode_statistics_msg` when a statistics record contains a negative value quantity.","commonSituations":"Loading historical Databento statistics/definition data containing negative volume fields (data-quality issues or vendor encoding quirks), or feeding already-converted/scaled data back through the decoder so values appear negative.","solutions":["Inspect the offending record and verify whether the negative value is a genuine data issue; exclude or correct the record.","If the semantics of the field allow negatives (e.g. net change), decode it with a signed type instead of `decode_optional_quantity`.","Pre-filter records: skip rows where the quantity field is negative before calling the decoder.","Catch the anyhow error in the record-processing closure and log/skip rather than aborting the whole range request."],"exampleFix":"// before\nlet qty = decode_optional_quantity(stat.quantity as i64)?;\n// after\nlet qty = if (stat.quantity as i64) < 0 && stat.quantity as i64 != i64::MAX { None } else { decode_optional_quantity(stat.quantity as i64)? };","handlingStrategy":"validation","validationCode":"fn quantity_valid(raw: i64) -> bool { raw == i64::MAX || raw >= 0 }","typeGuard":"fn is_negative_quantity(v: i64) -> bool { v != i64::MAX && v < 0 }","tryCatchPattern":"match decode_optional_quantity(raw) {\n    Ok(q) => use(q),\n    Err(e) => { log::warn!(\"bad quantity: {e}\"); Quantity::default() }\n}","preventionTips":["Reject or sanitize negative quantity fields in records before decoding.","Remember the two sentinels: i64::MAX = undefined, negatives = invalid.","Verify vendor data quality when statistics records report negative volumes."],"tags":["databento","decode","quantity","validation"],"backgroundTag":"invalid-argument-value","analyzedSha":"18893faf8b356be3320add8de2f861b0b647cf06","analyzedAt":"2026-09-08T20:49:34.690Z","contentChangedAt":"2026-09-08T20:49:34.690Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}