nautechsystems/nautilus_trader · error

Missing required timestamp for `{field_name}`

Error message

Missing required timestamp for `{field_name}`

What it means

`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.

Source

Thrown at crates/adapters/databento/src/decode/primitives.rs:342

pub fn decode_optional_quantity(value: i64) -> anyhow::Result<Option<Quantity>> {
    match value {
        i64::MAX => Ok(None),
        value if value >= 0 => Ok(Some(quantity_from_whole(value as u64))),
        value => anyhow::bail!("Invalid negative quantity: {value}"),
    }
}

/// Decodes a timestamp, returning an error if undefined.
///
/// Databento uses `u64::MAX` as `UNDEF_TIMESTAMP` sentinel for null timestamps.
///
/// # Errors
///
/// Returns an error if `value` is `u64::MAX` (undefined).
#[inline(always)]
pub fn decode_timestamp(value: u64, field_name: &str) -> anyhow::Result<UnixNanos> {
    if value == dbn::UNDEF_TIMESTAMP {
        anyhow::bail!("Missing required timestamp for `{field_name}`")
    } else {
        Ok(UnixNanos::from(value))
    }
}

/// Decodes a timestamp from the given optional value.
///
/// Databento uses `u64::MAX` as `UNDEF_TIMESTAMP` sentinel for null timestamps.
#[inline(always)]
#[must_use]
pub fn decode_optional_timestamp(value: u64) -> Option<UnixNanos> {
    if value == dbn::UNDEF_TIMESTAMP {
        None
    } else {
        Some(UnixNanos::from(value))
    }
}

View on GitHub (pinned to 18893faf8b)

Solutions

1. Use `decode_optional_timestamp` in the caller and handle `None` when the field is legitimately optional.
2. Filter out instrument definitions with undefined required timestamps before decoding.
3. Verify the Databento dataset/schema actually populates the timestamp field for the symbols requested.
4. Catch the error during instrument seeding and skip that instrument with a warning.

Example fix

// before
let activation = decode_timestamp(msg.activation, "activation")?;
// after
let activation = if msg.activation == dbn::UNDEF_TIMESTAMP { None } else { Some(decode_timestamp(msg.activation, "activation")?) };

fn timestamp_defined(v: u64) -> bool { v != dbn::UNDEF_TIMESTAMP }

fn is_undefined_timestamp(v: u64) -> bool { v == dbn::UNDEF_TIMESTAMP }

match decode_timestamp(msg.activation, "activation") {
    Ok(ts) => use(ts),
    Err(e) => { log::warn!("no activation ts: {e}"); UnixNanos::default() }
}

When it happens

Trigger: `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.

Common situations: 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.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Missing required price for `{field_name}`
• Invalid negative quantity: {value}
• Invalid negative multiplier: {v}
• Failed to decode instrument {instrument_id}: {e}
• Invalid data element not `QuoteTick`, was {data:?}

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