clockworklabs/SpacetimeDB · warning

Timestamp with i64 microseconds before Unix epoch overflows

Error message

Timestamp with i64 microseconds before Unix epoch overflows SystemTime

What it means

`Timestamp::to_system_time` subtracts the pre-epoch magnitude from `SystemTime::UNIX_EPOCH` via `checked_sub(...).expect("...before Unix epoch overflows SystemTime")`. This covers Timestamps before 1970; the subtraction only overflows on platforms whose SystemTime cannot represent ~292 years before the epoch, which none of Linux/macOS/Windows do — so this is a portability guard, rarely hit in practice.

Source

Thrown at crates/sats/src/timestamp.rs:97

        )
    }

    /// Convert `self` into a [`SystemTime`] which refers to approximately the same point in time.
    ///
    /// This conversion may lose precision, as [`SystemTime`]'s prevision varies depending on platform.
    /// E.g. Unix targets have microsecond precision, but Windows only 100-microsecond precision.
    ///
    /// This conversion may panic if `self` is out of bounds for [`SystemTime`].
    /// We are not aware of any platforms for which [`SystemTime`] offers a smaller range than [`Timestamp`],
    /// but such a platform may exist.
    pub fn to_system_time(self) -> SystemTime {
        match self.to_duration_since_unix_epoch() {
            Ok(positive) => SystemTime::UNIX_EPOCH
                .checked_add(positive)
                .expect("Timestamp with i64 microseconds since Unix epoch overflows SystemTime"),
            Err(negative) => SystemTime::UNIX_EPOCH
                .checked_sub(negative)
                .expect("Timestamp with i64 microseconds before Unix epoch overflows SystemTime"),
        }
    }

    /// Convert a [`SystemTime`] into a [`Timestamp`] which refers to approximately the same point in time.
    ///
    /// This conversion may panic if `system_time` is out of bounds for [`Duration`].
    /// [`SystemTime`]'s range is larger than [`Timestamp`] on both Unix and Windows targets,
    /// so times in the far past or far future may panic.
    /// [`Timestamp`]'s range is approximately 292 years before and after the Unix epoch.
    pub fn from_system_time(system_time: SystemTime) -> Self {
        let duration = system_time
            .duration_since(SystemTime::UNIX_EPOCH)
            .expect("SystemTime predates the Unix epoch");
        Self::from_duration_since_unix_epoch(duration)
    }

    /// Returns the [`Duration`] delta between `self` and `earlier`, if `earlier` predates `self`.
    ///

View on GitHub (pinned to 524b4487d9)

Solutions

1. Keep pre-epoch math in Timestamp; convert to SystemTime only where the value is known reasonable.
2. Validate the magnitude against the platform's representable range before converting.
3. Treat hits of this expect as a signal you are converting unvalidated extreme values.

Example fix

// before
let st = ts.to_system_time(); // may panic for far pre-epoch values on niche platforms

// after: gate the conversion
let st = if ts >= Timestamp::from_micros_since_unix_epoch(MIN_SAFE) { ts.to_system_time() } else { SystemTime::UNIX_EPOCH };

// Guard pre-epoch magnitudes before converting
if ts < Timestamp::from_micros_since_unix_epoch(-MIN_SAFE_MICROS) { /* skip/fallback */ } else { let st = ts.to_system_time(); }

When it happens

Trigger: Converting a Timestamp with a large negative micros value (far pre-epoch) to SystemTime on a platform with a narrow pre-1970 clock range; unreachable on mainstream targets.

Common situations: Fuzzing with extreme negative timestamps; exotic embedded/wasm targets with restricted clock representations.

Related errors

• Timestamp with i64 microseconds since Unix epoch overflows S
• Duration since Unix epoch overflows i64 microseconds
• Duration overflows i64 microseconds
• SystemTime predates the Unix epoch
• Timestamp is outside of the representable range of JS's Date

AI-assisted analysis of clockworklabs/SpacetimeDB@524b4487d9 (2026-08-16). Data as JSON: /api/errors/748e886ec582304b. Report an issue: GitHub.