nautechsystems/nautilus_trader · error · ValueError

pandas is required for nanosecond-precision datetimes

Error message

pandas is required for nanosecond-precision datetimes

What it means

Raised in the pandas-free fallback of unix_nanos_to_dt when the input timestamp has a sub-microsecond nanosecond remainder: the stdlib datetime this path builds only holds microsecond precision, so converting would silently lose the trailing digits. The input at fault is any nanos value not evenly divisible by 1000.

Solutions

  1. Install pandas so unix_nanos_to_dt can return a nanosecond-precision pd.Timestamp
  2. Round or truncate the timestamp to microsecond alignment before calling the converter
Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at python/nautilus_trader/core/datetime.py:74 when the library encounters an invalid state.

Common situations: See trigger scenarios.


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

Appendix: source

Thrown at python/nautilus_trader/core/datetime.py:74

_NANOS_PER_MICROSECOND = 1_000
_NANOS_PER_SECOND = 1_000_000_000
_SECONDS_PER_DAY = 86_400
_MICROSECOND_PRECISION_DIGITS = 6
_UNIX_EPOCH = datetime(1970, 1, 1, tzinfo=UTC)


def unix_nanos_to_dt(nanos: int) -> datetime | pd.Timestamp:
    """
    Return the UTC datetime for the given UNIX timestamp in nanoseconds.
    """
    try:
        import pandas as pd
    except ImportError:
        seconds, nanos_remainder = divmod(int(nanos), _NANOS_PER_SECOND)
        microseconds, nanos_remainder = divmod(nanos_remainder, _NANOS_PER_MICROSECOND)
        if nanos_remainder:
            raise ValueError("pandas is required for nanosecond-precision datetimes") from None

        return _UNIX_EPOCH + timedelta(seconds=seconds, microseconds=microseconds)

    return pd.Timestamp(int(nanos), unit="ns", tz="UTC")


def dt_to_unix_nanos(value: int | str | datetime | pd.Timestamp | None) -> int:
    """
    Return the UNIX timestamp in nanoseconds for the given datetime-like value.
    """
    if value is None:
        raise ValueError("value must not be None")

    try:
        import pandas as pd
    except ImportError:
        if isinstance(value, int):
            return value

View on GitHub (pinned to 18893faf8b)