agalwood/Motrix · error · RangeError

taskId must be a string

Error message

taskId must be a string

What it means

RangeError from assertTaskId when the argument is not a string. This is a low-level validator used to gate IPC input; it deliberately throws RangeError (not AppError) for malformed primitives before any task lookup occurs.

Source

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

export const MAX_ERROR_MESSAGE_LENGTH = 2_048
export const MAX_ERROR_DETAIL_KEY_LENGTH = 128
export const MAX_ERROR_DETAIL_PARAMS_JSON_LENGTH = 2_048
export const MAX_SAMPLE_FLAGS = 2_147_483_647

const STATUS_VALUES = new Set<string>(Object.values(TaskStatus))
const EVENT_KIND_VALUES = new Set<string>(Object.values(TaskHistoryEventKind))
const ACCURACY_VALUES = new Set<string>(Object.values(TaskHistoryAccuracy))
const DELIVERY_VALUES = new Set<string>(Object.values(TaskHistoryDelivery))
const ACTIVE_RESUME_STATUSES = new Set<TaskStatus>([
  TaskStatus.FetchingMetadata,
  TaskStatus.Downloading,
  TaskStatus.Finalizing,
  TaskStatus.Seeding,
])

export function assertTaskId(taskId: string): string {
  if (typeof taskId !== 'string') {
    throw new RangeError('taskId must be a string')
  }
  if (taskId.length > MAX_TASK_ID_LENGTH) {
    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

View on GitHub (pinned to 1a708ee577)

Solutions

1. Coerce or stringify the taskId before calling: String(value).
2. Validate at the boundary that taskId is a string and reject earlier.
3. Fix the sender to always send taskId as a string.

Example fix

// before
assertTaskId(payload.taskId) // payload.taskId is 12345 -> RangeError

// after
assertTaskId(typeof payload.taskId === 'number' ? String(payload.taskId) : payload.taskId)

// Coerce to string before validating.
const id = typeof raw === 'number' ? String(raw) : raw
if (typeof id !== 'string') { /* reject early */ }
assertTaskId(id)

function isStringTaskId(v: unknown): v is string {
  return typeof v === 'string'
}

try {
  assertTaskId(maybeId)
} catch (err) {
  if (err instanceof RangeError && /must be a string/.test(err.message)) {
    // reject the IPC payload; require a string taskId
  } else throw err
}

When it happens

Trigger: assertTaskId is called with a value where typeof !== 'string' — e.g. a number, undefined, null, object, or boolean.

Common situations: An IPC payload passed a numeric task id; a missing field defaulted to undefined; deserialization produced a non-string; a caller passed an object whose taskId field was unboxed incorrectly.

Related errors

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

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