{"record":{"id":"128e2794e3ecebf4","repo":"agalwood/Motrix","slug":"label-exceeds-the-javascript-safe-integer-range","errorCode":null,"errorMessage":"${label} exceeds the JavaScript safe integer range","messagePattern":"(.+?) exceeds the JavaScript safe integer range","errorType":"validation","errorClass":"RangeError","httpStatus":null,"severity":"error","filePath":"src/core/inspector-activity/validators.ts","lineNumber":83,"sourceCode":"    throw new RangeError(`${label} must be a non-negative safe integer`)\n  }\n  return value\n}\n\nexport function assertNonNegativeBigInt(value: bigint, label: string): bigint {\n  if (typeof value !== 'bigint' || value < 0n) {\n    throw new RangeError(`${label} must be a non-negative bigint`)\n  }\n  return value\n}\n\nexport function normalizeSpeed(value: number, label: string): number {\n  if (!Number.isFinite(value) || value < 0) {\n    throw new RangeError(`${label} must be finite and non-negative`)\n  }\n  const normalized = Math.round(value)\n  if (!Number.isSafeInteger(normalized)) {\n    throw new RangeError(`${label} exceeds the JavaScript safe integer range`)\n  }\n  return normalized\n}\n\nexport function saturatingAddSignedInt64(\n  current: bigint,\n  delta: bigint\n): { value: bigint; saturated: boolean } {\n  assertNonNegativeBigInt(current, 'current')\n  assertNonNegativeBigInt(delta, 'delta')\n  if (current > MAX_SIGNED_SQLITE_INTEGER) {\n    throw new RangeError('current exceeds the signed int64 range')\n  }\n  if (delta > MAX_SIGNED_SQLITE_INTEGER - current) {\n    return { value: MAX_SIGNED_SQLITE_INTEGER, saturated: true }\n  }\n  return { value: current + delta, saturated: false }\n}","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/agalwood/Motrix/blob/1a708ee57746c434e2c67a44bbf0906a976afea4/src/core/inspector-activity/validators.ts#L65-L101","documentation":"`normalizeSpeed` rounds the input with `Math.round` and then asserts the result is a JavaScript safe integer (within `Number.MAX_SAFE_INTEGER`, ~9.007e15). It throws this `RangeError` only when the input was finite and non-negative but rounded above the safe-integer bound. Speeds that large cannot be stored as a normal integer, so the validator refuses rather than silently truncating. The `label` in the message names which field overflowed (e.g. `peakDownloadBps`, `samples[3].down`).","triggerScenarios":"Calling `normalizeTransferSamples(samples)` or `validateCheckpoint(checkpoint)` with a sample whose `down`/`up`, or a checkpoint's `peakDownloadBps`/`peakUploadBps`, rounds to a value above 2^53-1. Concretely: a `SpeedPoint` carrying a downstream-aggregated bytes-per-second number that overflowed a 32-bit accumulator, or a bits-vs-bytes unit mismatch multiplying a legal speed by 8.","commonSituations":"Aggregator code that sums speeds across many peers without capping the result; tests hand-crafting unrealistic speeds; misreading an already-large byte count as bps; foreign telemetry with different units.","solutions":["Clamp the speed before passing it in: `Math.min(Math.round(value), Number.MAX_SAFE_INTEGER)`.","Verify the upstream unit — the field is bytes/second, not bits/second or bytes/interval.","Audit the producer that fills `SpeedPoint.down/up` for an overflowed accumulator.","If genuinely large speeds are expected, store the field as a bigint and redesign the validator instead of clamping."],"exampleFix":"// before\ncheckpoint.peakDownloadBps = aggregateBps  // aggregateBps > 2^53\n// after\ncheckpoint.peakDownloadBps = Math.min(aggregateBps, Number.MAX_SAFE_INTEGER)","handlingStrategy":"validation","validationCode":"function safeSpeed(value: number, label: string): number {\n  if (!Number.isFinite(value) || value < 0)\n    throw new RangeError(`${label} must be finite and non-negative`)\n  return Math.min(Math.round(value), Number.MAX_SAFE_INTEGER)\n}","typeGuard":null,"tryCatchPattern":"try {\n  normalizeSpeed(value, label)\n} catch (err) {\n  if (err instanceof RangeError && err.message.endsWith('exceeds the JavaScript safe integer range')) {\n    value = Number.MAX_SAFE_INTEGER\n  } else throw err\n}","preventionTips":["Clamp any aggregated speed to MAX_SAFE_INTEGER at the producer.","Treat a speed overflow as a producer bug — investigate the unit, do not silently clamp in production.","Unit-test sample fixtures with values at and above 2^53."],"tags":["validation","range-error","numbers","inspector-activity"],"backgroundTag":null,"analyzedSha":"1a708ee57746c434e2c67a44bbf0906a976afea4","analyzedAt":"2026-08-12T16:18:09.346Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}