clockworklabs/SpacetimeDB · error · RangeError

Timestamp is outside of the representable range of JS's Date

Error message

Timestamp is outside of the representable range of JS's Date

What it means

The spacetimedb::duration!(...) proc-macro parses its input with humantime::parse_duration. String literals must be valid humantime durations ("10s", "1h 30m", "500ms"); integer literals are stringified to bare digits, which humantime rejects because they carry no unit. The syn error is spanned to the offending literal.

Solutions

1. Use a unit-suffixed string literal: spacetimedb::duration!("10s").
2. For composite durations use humantime syntax: "1h 30m", "2days 4h".
3. Check humantime's accepted units: ns, us, ms, s/sec/seconds, m/min/minutes, h/hours, d/days (plus plurals).

Example fix

// before
const T: Duration = spacetimedb::duration!(500);      // bare int: no unit
const T: Duration = spacetimedb::duration!("1hr");    // unknown unit

// after
const T: Duration = spacetimedb::duration!("500ms");
const T: Duration = spacetimedb::duration!("1h");

# CI check: flag unit-less integers passed to the duration macro
rg -n 'duration!\(\s*[0-9]+\s*\)' src/ && exit 1 || true

When it happens

Trigger: spacetimedb::duration!(5) (integer, no unit) or duration!("5"), duration!("1hr"), duration!("10 seconds-ish") — any literal humantime cannot parse.

Common situations: Assuming the macro takes a raw count of seconds/milliseconds; unit typos like 1hr instead of 1hour/1h; pasting durations from a config format with different syntax.

Related errors

• Cannot convert to : expected bigint, integer number, or…
• Invalid UUID: must be between 0 and `MAX_UUID_BIGINT`
• must specify view accessor, e.g. `#
• scheduled tables must have a `#[primary_key] #[auto_inc]…
• Timestamp is outside of the representable range for ISO…

AI-assisted analysis of clockworklabs/SpacetimeDB@6dee26c6ef (2026-08-20). Data as JSON: /api/errors/b17396404cbd8404. Report an issue: GitHub.

Appendix: source

Thrown at crates/bindings-typescript/src/lib/timestamp.ts:110

    const millis = date.getTime();
    const micros = BigInt(millis) * Timestamp.MICROS_PER_MILLIS;
    return new Timestamp(micros);
  }

  /**
   * Get a `Date` representing approximately the same point in time as `this`.
   *
   * This method truncates to millisecond precision,
   * and throws `RangeError` if the `Timestamp` is outside the range representable as a `Date`.
   */
  toDate(): Date {
    const micros = this.__timestamp_micros_since_unix_epoch__;
    const millis = micros / Timestamp.MICROS_PER_MILLIS;
    if (
      millis > BigInt(Number.MAX_SAFE_INTEGER) ||
      millis < BigInt(Number.MIN_SAFE_INTEGER)
    ) {
      throw new RangeError(
        "Timestamp is outside of the representable range of JS's Date"
      );
    }
    return new Date(Number(millis));
  }

  /**
   * Get an ISO 8601 / RFC 3339 formatted string representation of this timestamp with microsecond precision.
   *
   * This method preserves the full microsecond precision of the timestamp,
   * and throws `RangeError` if the `Timestamp` is outside the range representable in ISO format.
   *
   * @returns ISO 8601 formatted string with microsecond precision (e.g., '2025-02-17T10:30:45.123456Z')
   */
  toISOString(): string {
    const micros = this.__timestamp_micros_since_unix_epoch__;
    const millis = micros / Timestamp.MICROS_PER_MILLIS;

View on GitHub (pinned to 6dee26c6ef)