{"record":{"id":"ffd9e51fa7805ae5","repo":"agalwood/Motrix","slug":"label-must-be-a-non-negative-bigint","errorCode":null,"errorMessage":"${label} must be a non-negative bigint","messagePattern":"(.+?) must be a non-negative bigint","errorType":"validation","errorClass":"RangeError","httpStatus":null,"severity":"error","filePath":"src/core/inspector-activity/validators.ts","lineNumber":72,"sourceCode":"  if (!Number.isSafeInteger(value) || value <= 0) {\n    throw new RangeError(`${label} must be a positive safe integer`)\n  }\n  return value\n}\n\nexport function assertNonNegativeSafeInteger(\n  value: number,\n  label: string\n): number {\n  if (!Number.isSafeInteger(value) || value < 0) {\n    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","sourceCodeStart":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/agalwood/Motrix/blob/1a708ee57746c434e2c67a44bbf0906a976afea4/src/core/inspector-activity/validators.ts#L54-L90","documentation":"RangeError from assertNonNegativeBigInt when value is not a bigint or is < 0n. Used for byte counters (downloaded/uploaded sizes) that overflow Number's safe-integer range and must be represented as BigInt.","triggerScenarios":"assertNonNegativeBigInt(value, label) with typeof value !== 'bigint' || value < 0n. E.g. a plain number passed where bigint is required, a negative bigint, or undefined.","commonSituations":"Caller passed a Number instead of BigInt for a large byte count; a subtraction underflowed to a negative bigint; JSON deserialization produced a Number (JSON has no BigInt) that was not converted; missing field defaulted to undefined.","solutions":["Convert numbers to BigInt before calling: BigInt(value).","Clamp with value < 0n ? 0n : value.","Use a BigInt-aware JSON parser for round-tripping large counters.","Default the field to 0n rather than undefined."],"exampleFix":"// before\nassertNonNegativeBigInt(payload.bytesDownloaded, 'bytesDownloaded') // it's a number -> RangeError\n\n// after\nconst bytes = typeof payload.bytesDownloaded === 'bigint' ? payload.bytesDownloaded : BigInt(payload.bytesDownloaded)\nassertNonNegativeBigInt(bytes < 0n ? 0n : bytes, 'bytesDownloaded')","handlingStrategy":"validation","validationCode":"// Convert numbers to BigInt and clamp before validating.\nconst v = typeof raw === 'bigint' ? raw : BigInt(raw)\nassertNonNegativeBigInt(v < 0n ? 0n : v, 'bytesDownloaded')","typeGuard":"function isNonNegativeBigInt(v: unknown): v is bigint {\n  return typeof v === 'bigint' && v >= 0n\n}","tryCatchPattern":"try {\n  assertNonNegativeBigInt(value, 'bytesDownloaded')\n} catch (err) {\n  if (err instanceof RangeError && /non-negative bigint/.test(err.message)) {\n    // default to 0n\n  } else throw err\n}","preventionTips":["Use BigInt for byte counters that may exceed 2^53-1.","Use a BigInt-aware JSON serializer for round-tripping.","Default large-counter fields to 0n.","Guard subtractions against underflow with `x < 0n ? 0n : x`."],"tags":["validation","range-error","bigint","byte-counter","non-negative"],"backgroundTag":null,"analyzedSha":"1a708ee57746c434e2c67a44bbf0906a976afea4","analyzedAt":"2026-08-12T16:18:09.346Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}