agalwood/Motrix · error · RangeError

${label} must be a non-negative safe integer

Error message

${label} must be a non-negative safe integer

What it means

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.

Source

Thrown at src/core/inspector-activity/validators.ts:65

  return normalized
}

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

export function assertNonNegativeSafeInteger(
  value: number,
  label: string
): number {
  if (!Number.isSafeInteger(value) || value < 0) {
    throw new RangeError(`${label} must be a non-negative safe integer`)
  }
  return value
}

export function assertNonNegativeBigInt(value: bigint, label: string): bigint {
  if (typeof value !== 'bigint' || value < 0n) {
    throw new RangeError(`${label} must be a non-negative bigint`)
  }
  return value
}

export function normalizeSpeed(value: number, label: string): number {
  if (!Number.isFinite(value) || value < 0) {
    throw new RangeError(`${label} must be finite and non-negative`)
  }
  const normalized = Math.round(value)
  if (!Number.isSafeInteger(normalized)) {
    throw new RangeError(`${label} exceeds the JavaScript safe integer range`)

View on GitHub (pinned to 1a708ee577)

Solutions

1. Clamp to 0 with Math.max(0, Math.trunc(value)).
2. Use a sentinel other than -1 for 'unset' (e.g. null) and skip validation when unset.
3. Validate non-negative at the producer.

Example fix

// before
assertNonNegativeSafeInteger(payload.offset, 'offset') // payload.offset = -1 -> RangeError

// after
const offset = payload.offset == null ? 0 : Math.max(0, Math.trunc(payload.offset))
assertNonNegativeSafeInteger(offset, 'offset')

// Clamp non-negative integers before validating.
const v = Math.max(0, Math.trunc(Number(raw)))
assertNonNegativeSafeInteger(Number.isSafeInteger(v) ? v : 0, 'offset')

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

try {
  assertNonNegativeSafeInteger(value, 'offset')
} catch (err) {
  if (err instanceof RangeError && /non-negative safe integer/.test(err.message)) {
    // default to 0
  } else throw err
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• ${label} must be a positive safe integer
• ${label} must be a non-negative bigint
• ${label} must be finite and non-negative
• taskId must be a string
• taskId must contain between 1 and ${MAX_TASK_ID_LENGTH} char

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