agalwood/Motrix · error · RangeError

${label} must be a positive safe integer timestamp

Error message

${label} must be a positive safe integer timestamp

What it means

Thrown by requireSafePositiveTimestamp when the value is not a safe integer OR is <= 0. Stricter than requireSafeTimestamp: it enforces that a timestamp denotes a real forward-pointing instant (used for expiry, created-at, scheduled times).

Source

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

  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. Distinguish 'unset' from 'set' at the type level (use undefined/null) instead of sentinel 0.
2. Validate the upstream payload has the field before calling the guard.
3. If 0 is a legitimate sentinel in your schema, branch around it rather than passing it to the positive guard.
4. For computed deltas, clamp or branch on the sign before validation.

Example fix

// before
requireSafePositiveTimestamp(expiry ?? 0, 'expiry')
// after
if (expiry === undefined) throw new TypeError('expiry required')
requireSafePositiveTimestamp(expiry, 'expiry')

function isPositiveSafeTimestamp(value: unknown): value is number {
  return typeof value === 'number' && Number.isSafeInteger(value) && value > 0
}
if (input.expiry === undefined || !isPositiveSafeTimestamp(input.expiry)) {
  throw new TypeError('expiry must be a positive safe integer')
}
requireSafePositiveTimestamp(input.expiry, 'expiry')

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

try {
  requireSafePositiveTimestamp(expiry, 'expiry')
} catch (e) {
  if (e instanceof RangeError) {
    // treat as 'no expiry set' or reject the payload
  } else throw e
}

When it happens

Trigger: Calling requireSafePositiveTimestamp(value, label) with 0, a negative number, NaN, or a fractional value. Typical when an optional timestamp defaulted to 0, or a Date is in the past represented as a negative delta.

Common situations: Defaulting an 'expiry' or 'notBefore' field to 0 meaning 'unset'; subtracting two timestamps and passing the result; receiving 0 from a missing JSON field; clock-skew corrections that produce non-positive values.

Related errors

• ${label} must be a 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/139b1f9e315e24db. Report an issue: GitHub.