agalwood/Motrix · error · RangeError

toStatus is required

Error message

toStatus is required

What it means

`validateHistoryEventInput` allows `fromStatus` to be `null` (for the first transition) but requires `toStatus` to be a concrete `TaskStatus`. After `assertStatus(input.toStatus, ...)` succeeds, this `RangeError` fires only if `toStatus === null`. Every history event must record the status it lands in.

Source

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

    input.runtimeGeneration,
    'runtimeGeneration',
    MAX_EVENT_KEY_LENGTH
  )
  assertPositiveSafeInteger(input.occurredAt, 'occurredAt')
  assertNonNegativeSafeInteger(input.occurredMonotonicMs, 'occurredMonotonicMs')
  if (!EVENT_KIND_VALUES.has(input.kind)) {
    throw new RangeError('kind is not a legal history event kind')
  }
  if (!ACCURACY_VALUES.has(input.accuracy)) {
    throw new RangeError('accuracy is not legal')
  }
  if (!DELIVERY_VALUES.has(input.delivery)) {
    throw new RangeError('delivery is not legal')
  }
  assertStatus(input.fromStatus, 'fromStatus')
  assertStatus(input.toStatus, 'toStatus')
  if (input.toStatus === null) {
    throw new RangeError('toStatus is required')
  }
  assertBoundedText(input.errorCode, 'errorCode', MAX_ERROR_CODE_LENGTH)
  assertBoundedText(
    input.errorMessage,
    'errorMessage',
    MAX_ERROR_MESSAGE_LENGTH
  )
  assertBoundedText(
    input.errorDetailKey,
    'errorDetailKey',
    MAX_ERROR_DETAIL_KEY_LENGTH
  )
  assertBoundedDetailParams(
    input.errorDetailParams,
    'errorDetailParams',
    MAX_ERROR_DETAIL_PARAMS_JSON_LENGTH
  )

View on GitHub (pinned to 1a708ee577)

Solutions

1. Resolve the destination status before constructing the event — defer submission until it is known.
2. If genuinely unknown, do not emit an event; emit one only at a real transition.
3. Map the source's 'no change' sentinel to the current persisted status.

Example fix

// before
event.toStatus = nextStatus  // nextStatus is null
// after
if (nextStatus === null) return  // no transition, no event
event.toStatus = nextStatus

if (input.toStatus === null) {
  // do not submit — no transition to record
  return
}

function hasToStatus<T extends { toStatus: unknown }>(e: T): e is T & { toStatus: string } {
  return e.toStatus !== null
}

When it happens

Trigger: Submitting an event with `toStatus: null` — usually because the producer used `fromStatus ?? toStatus`-style code that resolved to null, or because JSON deserialization defaulted a missing field to null.

Common situations: Building an event from a partial engine snapshot where the new status is not yet known; tests using `null` as a placeholder; bridge code forwarding the source's 'no change' sentinel without translating it.

Related errors

• ${label} is not a legal task status
• kind is not a legal history event kind
• Added must not have a fromStatus
• Started must enter an active status
• Paused must transition from active to paused

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