agalwood/Motrix · error · RangeError

${label} must be a positive safe integer

Error message

${label} must be a positive safe integer

What it means

RangeError from assertPositiveSafeInteger when the value is not a safe integer (NaN, Infinity, float, or outside Number.MIN/MAX_SAFE_INTEGER) or is <= 0. The label is interpolated so callers know which field failed. Used for strictly-positive counters (limits, offsets that must be >=1).

Source

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

    throw new RangeError(
      `taskId must contain between 1 and ${MAX_TASK_ID_LENGTH} characters`
    )
  }
  const normalized = taskId.trim()
  if (normalized.length === 0 || normalized.length > MAX_TASK_ID_LENGTH) {
    throw new RangeError(
      `taskId must contain between 1 and ${MAX_TASK_ID_LENGTH} characters`
    )
  }
  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`)
  }

View on GitHub (pinned to 1a708ee577)

Solutions

1. Coerce with Math.trunc/parseInt and clamp to a minimum of 1.
2. Default the field to a positive safe integer (e.g. 1 or a known default).
3. Validate range at the producer and reject <=0 or non-integer before calling.

Example fix

// before
assertPositiveSafeInteger(payload.limit, 'limit') // payload.limit = 0 -> RangeError

// after
const limit = Number.isFinite(payload.limit) && payload.limit > 0 ? Math.trunc(payload.limit) : DEFAULT_LIMIT
assertPositiveSafeInteger(limit, 'limit')

// Coerce + clamp to a positive safe integer before validating.
const v = Math.trunc(Number(raw))
const safe = Number.isSafeInteger(v) && v > 0 ? v : 1
assertPositiveSafeInteger(safe, 'limit')

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

try {
  assertPositiveSafeInteger(value, 'limit')
} catch (err) {
  if (err instanceof RangeError && /positive safe integer/.test(err.message)) {
    // fall back to a sane default limit
  } else throw err
}

When it happens

Trigger: assertPositiveSafeInteger(value, label) with !Number.isSafeInteger(value) || value <= 0. E.g. 0, -1, 1.5, NaN, Infinity, or a Number larger than 2^53-1.

Common situations: A default of 0 for a field that must be >=1; a float parsed from a string; NaN from a failed parseInt; an unbounded counter exceeding the safe-integer range; a negative value from a sign error.

Related errors

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

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