{"record":{"id":"b17396404cbd8404","repo":"clockworklabs/SpacetimeDB","slug":"timestamp-is-outside-of-the-representable-range-of","errorCode":null,"errorMessage":"Timestamp is outside of the representable range of JS's Date","messagePattern":"Timestamp is outside of the representable range of JS's Date","errorType":"exception","errorClass":"RangeError","httpStatus":null,"severity":"error","filePath":"crates/bindings-typescript/src/lib/timestamp.ts","lineNumber":110,"sourceCode":"    const millis = date.getTime();\n    const micros = BigInt(millis) * Timestamp.MICROS_PER_MILLIS;\n    return new Timestamp(micros);\n  }\n\n  /**\n   * Get a `Date` representing approximately the same point in time as `this`.\n   *\n   * This method truncates to millisecond precision,\n   * and throws `RangeError` if the `Timestamp` is outside the range representable as a `Date`.\n   */\n  toDate(): Date {\n    const micros = this.__timestamp_micros_since_unix_epoch__;\n    const millis = micros / Timestamp.MICROS_PER_MILLIS;\n    if (\n      millis > BigInt(Number.MAX_SAFE_INTEGER) ||\n      millis < BigInt(Number.MIN_SAFE_INTEGER)\n    ) {\n      throw new RangeError(\n        \"Timestamp is outside of the representable range of JS's Date\"\n      );\n    }\n    return new Date(Number(millis));\n  }\n\n  /**\n   * Get an ISO 8601 / RFC 3339 formatted string representation of this timestamp with microsecond precision.\n   *\n   * This method preserves the full microsecond precision of the timestamp,\n   * and throws `RangeError` if the `Timestamp` is outside the range representable in ISO format.\n   *\n   * @returns ISO 8601 formatted string with microsecond precision (e.g., '2025-02-17T10:30:45.123456Z')\n   */\n  toISOString(): string {\n    const micros = this.__timestamp_micros_since_unix_epoch__;\n    const millis = micros / Timestamp.MICROS_PER_MILLIS;\n","sourceCodeStart":92,"sourceCodeEnd":128,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/524b4487d949b61a07d4f39c862d1290259dfd20/crates/bindings-typescript/src/lib/timestamp.ts#L92-L128","documentation":"Timestamp.toDate() converts microseconds-since-epoch to JS Date milliseconds. The millis value must fit within +/-Number.MAX_SAFE_INTEGER (roughly +/-285,000 years); outside that, Number(millis) would silently lose precision, so the method throws RangeError instead.","triggerScenarios":"Calling .toDate() on a Timestamp built from unit-confused or corrupted micros - e.g. nanoseconds passed as micros, or a value multiplied by 1000 twice - so that |micros / 1000n| exceeds 2^53-1.","commonSituations":"Hand-constructing Timestamps from server data in the wrong precision; BigInt arithmetic bugs (shift/multiply errors); test fixtures using sentinel values like Number.MAX_VALUE.","solutions":["Fix the precision at the source: construct Timestamps from microseconds since the Unix epoch","Range-check before converting and keep extreme values as Timestamp for comparisons instead of Date","Prefer the microsecond accessors and toISOString-style formatting over Date when values may be extreme"],"exampleFix":"// before\nconst d = ts.toDate(); // extreme micros -> RangeError\n\n// after\nconst MAX_MS = BigInt(Number.MAX_SAFE_INTEGER);\nconst ms = ts.__timestamp_micros_since_unix_epoch__ / 1000n;\nconst d = ms >= -MAX_MS && ms <= MAX_MS ? ts.toDate() : null; // null => handle out-of-band","handlingStrategy":"validation","validationCode":"const MAX_SAFE_MILLIS = BigInt(Number.MAX_SAFE_INTEGER);\nfunction timestampToDateSafe(ts: Timestamp): Date | null {\n  const millis = ts.__timestamp_micros_since_unix_epoch__ / 1000n;\n  if (millis > MAX_SAFE_MILLIS || millis < -MAX_SAFE_MILLIS) return null;\n  return ts.toDate();\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Construct Timestamps only from microseconds since the Unix epoch","Keep comparisons on Timestamp values; convert to Date only at the display boundary","Add unit tests covering extreme values so precision bugs surface in CI, not production"],"tags":["timestamp","date","range-error","javascript","bigint"],"backgroundTag":"timestamp-out-of-range","analyzedSha":"524b4487d949b61a07d4f39c862d1290259dfd20","analyzedAt":"2026-08-16T23:58:54.611Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}