agalwood/Motrix · error · RangeError

${label} must be a safe integer timestamp

Error message

${label} must be a safe integer timestamp

What it means

Thrown by requireSafeTimestamp when a numeric value is not a safe integer. This is a guard used at trust boundaries (inputs, persisted timestamps) to reject NaN, Infinity, fractional seconds, or values beyond 2^53 before they reach time arithmetic.

Source

Thrown at src/core/lib/sqlite-integers.ts:38

    throw new RangeError(`${label} exceeds the JavaScript safe integer range`)
  }
  return Number(value)
}

export function nonNegativeIntegerFromBigInt(
  value: bigint,
  label: string
): number {
  const converted = safeIntegerFromSql(value, label)
  if (converted < 0) {
    throw new RangeError(`${label} must be non-negative`)
  }
  return converted
}

export function requireSafeTimestamp(value: number, label: string): void {
  if (!Number.isSafeInteger(value)) {
    throw new RangeError(`${label} must be a safe integer timestamp`)
  }
}

export function requireSafePositiveTimestamp(
  value: number,
  label: string
): void {
  if (!Number.isSafeInteger(value) || value <= 0) {
    throw new RangeError(`${label} must be a positive safe integer timestamp`)
  }
}

View on GitHub (pinned to 1a708ee577)

Solutions

1. Coerce and unit-normalize the value before calling the guard (e.g. Math.trunc, divide/multiply by 1000 as needed).
2. Validate the upstream source returned a finite integer string before Number()-ing it.
3. If fractional seconds are intended, switch to a storing scheme that keeps whole-second precision.
4. Log the raw input alongside the label to find which field is malformed.

Example fix

// before
requireSafeTimestamp(Number(req.query.t), 't')
// after
const t = Number(req.query.t)
if (!Number.isFinite(t)) throw new TypeError('bad t')
requireSafeTimestamp(Math.trunc(t), 't')

function isSafeTimestamp(value: unknown): value is number {
  return typeof value === 'number' && Number.isSafeInteger(value)
}
if (!isSafeTimestamp(input.t)) {
  throw new TypeError(`t must be a safe integer; got ${input.t}`)
}
requireSafeTimestamp(input.t, 't')

function isSafeTimestamp(value: unknown): value is number {
  return typeof value === 'number' && Number.isSafeInteger(value)
}

try {
  requireSafeTimestamp(t, 't')
} catch (e) {
  if (e instanceof RangeError) {
    // reject the input payload rather than crashing
  } else throw e
}

When it happens

Trigger: Calling requireSafeTimestamp(value, label) where value is NaN (e.g. Number(undefined)), a float like 1700000000.5, Infinity, or a millisecond timestamp accidentally treated as seconds that exceeds the safe range.

Common situations: Mixing seconds and milliseconds epoch units; parsing a timestamp from an untrusted API that returned a string (Number('N/A') = NaN); floating-point division that introduced a fractional component.

Related errors

• ${label} must be a positive safe integer timestamp
• ${label} must be non-negative
• invalid-url-scheme
• invalid Chrome extension ID: ${id}
• invalid Firefox extension ID: ${id}

AI-assisted analysis of agalwood/Motrix@1a708ee577 (2026-08-12). Data as JSON: /api/errors/e46d66f8273203c6. Report an issue: GitHub.