{"record":{"id":"b5e26cae3f4c8d02","repo":"agalwood/Motrix","slug":"label-must-be-a-non-negative-safe-integer","errorCode":null,"errorMessage":"${label} must be a non-negative safe integer","messagePattern":"(.+?) must be a non-negative safe integer","errorType":"validation","errorClass":"RangeError","httpStatus":null,"severity":"error","filePath":"src/core/inspector-activity/validators.ts","lineNumber":65,"sourceCode":"  return normalized\n}\n\nexport function assertPositiveSafeInteger(\n  value: number,\n  label: string\n): number {\n  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`)","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/agalwood/Motrix/blob/1a708ee57746c434e2c67a44bbf0906a976afea4/src/core/inspector-activity/validators.ts#L47-L83","documentation":"RangeError from assertNonNegativeSafeInteger when the value is not a safe integer or is negative (< 0). Like error 36 but allows zero. Used for counters/offsets that may legitimately be 0 but never negative.","triggerScenarios":"assertNonNegativeSafeInteger(value, label) with !Number.isSafeInteger(value) || value < 0. E.g. -1, -0.5, NaN, Infinity, a float, or a Number beyond the safe range.","commonSituations":"A subtraction underflowed to negative; NaN from parsing; a float where an integer was expected; a default of -1 used as 'unset' but passed to this stricter validator.","solutions":["Clamp to 0 with Math.max(0, Math.trunc(value)).","Use a sentinel other than -1 for 'unset' (e.g. null) and skip validation when unset.","Validate non-negative at the producer."],"exampleFix":"// before\nassertNonNegativeSafeInteger(payload.offset, 'offset') // payload.offset = -1 -> RangeError\n\n// after\nconst offset = payload.offset == null ? 0 : Math.max(0, Math.trunc(payload.offset))\nassertNonNegativeSafeInteger(offset, 'offset')","handlingStrategy":"validation","validationCode":"// Clamp non-negative integers before validating.\nconst v = Math.max(0, Math.trunc(Number(raw)))\nassertNonNegativeSafeInteger(Number.isSafeInteger(v) ? v : 0, 'offset')","typeGuard":"function isNonNegativeSafeInt(v: unknown): v is number {\n  return typeof v === 'number' && Number.isSafeInteger(v) && v >= 0\n}","tryCatchPattern":"try {\n  assertNonNegativeSafeInteger(value, 'offset')\n} catch (err) {\n  if (err instanceof RangeError && /non-negative safe integer/.test(err.message)) {\n    // default to 0\n  } else throw err\n}","preventionTips":["Use null (not -1) as an 'unset' sentinel and skip validation when unset.","Guard subtractions against underflow with Math.max(0, ...).","Clamp at the producer."],"tags":["validation","range-error","number","safe-integer","non-negative"],"backgroundTag":null,"analyzedSha":"1a708ee57746c434e2c67a44bbf0906a976afea4","analyzedAt":"2026-08-12T16:18:09.346Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}