{"record":{"id":"4294a83faa6c1b0c","repo":"nautechsystems/nautilus_trader","slug":"missing-required-timestamp-for-field-name","errorCode":null,"errorMessage":"Missing required timestamp for `{field_name}`","messagePattern":"Missing required timestamp for `(.+?)`","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/adapters/databento/src/decode/primitives.rs","lineNumber":342,"sourceCode":"pub 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}\n\n/// Decodes a timestamp from the given optional value.\n///\n/// Databento uses `u64::MAX` as `UNDEF_TIMESTAMP` sentinel for null timestamps.\n#[inline(always)]\n#[must_use]\npub fn decode_optional_timestamp(value: u64) -> Option<UnixNanos> {\n    if value == dbn::UNDEF_TIMESTAMP {\n        None\n    } else {\n        Some(UnixNanos::from(value))\n    }\n}\n","sourceCodeStart":324,"sourceCodeEnd":360,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/18893faf8b356be3320add8de2f861b0b647cf06/crates/adapters/databento/src/decode/primitives.rs#L324-L360","documentation":"`decode_timestamp` converts a `u64` nanosecond timestamp into `UnixNanos`, treating Databento's `UNDEF_TIMESTAMP` sentinel (`u64::MAX`) as an error when the timestamp is required. This prevents silently creating timestamps far in the future (u64::MAX nanos) for contract/spread definitions that must have a valid ts_event/ts_init.","triggerScenarios":"`decode_timestamp(value, field_name)` called with `value == dbn::UNDEF_TIMESTAMP`, typically while decoding futures/option contract or spread definition messages whose activation/deletion or event timestamps are unset.","commonSituations":"Instruments with no listing/expiry timestamps in Databento (e.g. pending or delisted contracts), requesting definition schemas whose timestamp columns are optional for that asset class.","solutions":["Use `decode_optional_timestamp` in the caller and handle `None` when the field is legitimately optional.","Filter out instrument definitions with undefined required timestamps before decoding.","Verify the Databento dataset/schema actually populates the timestamp field for the symbols requested.","Catch the error during instrument seeding and skip that instrument with a warning."],"exampleFix":"// before\nlet activation = decode_timestamp(msg.activation, \"activation\")?;\n// after\nlet activation = if msg.activation == dbn::UNDEF_TIMESTAMP { None } else { Some(decode_timestamp(msg.activation, \"activation\")?) };","handlingStrategy":"validation","validationCode":"fn timestamp_defined(v: u64) -> bool { v != dbn::UNDEF_TIMESTAMP }","typeGuard":"fn is_undefined_timestamp(v: u64) -> bool { v == dbn::UNDEF_TIMESTAMP }","tryCatchPattern":"match decode_timestamp(msg.activation, \"activation\") {\n    Ok(ts) => use(ts),\n    Err(e) => { log::warn!(\"no activation ts: {e}\"); UnixNanos::default() }\n}","preventionTips":["Always compare against dbn::UNDEF_TIMESTAMP (u64::MAX) before treating a timestamp as valid.","Use decode_optional_timestamp for fields that may be null.","Check dataset coverage for timestamps of the asset class you request."],"tags":["databento","decode","timestamp","sentinel-value"],"backgroundTag":"missing-required-argument","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"}