agalwood/Motrix · error · RangeError

delivery is not legal

Error message

delivery is not legal

What it means

`input.delivery` must be `TaskHistoryDelivery.Initial` (`'initial'`) or `TaskHistoryDelivery.Retry` (`'retry'`). It marks whether the event is submitted for the first time or redelivered after a failure. Throws this `RangeError` on any other value.

Source

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

export function validateHistoryEventInput(input: TaskHistoryEventInput): void {
  assertTaskId(input.taskId)
  assertPositiveSafeInteger(input.eventOrdinal, 'eventOrdinal')
  assertBoundedText(input.eventKey, 'eventKey', MAX_EVENT_KEY_LENGTH)
  assertBoundedText(
    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(

View on GitHub (pinned to 1a708ee577)

Solutions

1. Set `delivery` at the boundary: `Initial` on first submission, `Retry` on every redelivery.
2. Reference the enum, not the literal.
3. Reject events at the IPC edge whose delivery is not one of the two values.

Example fix

// before
input.delivery = attemptCount > 0 ? 'retransmit' : 'first'
// after
input.delivery = attemptCount > 0 ? TaskHistoryDelivery.Retry : TaskHistoryDelivery.Initial

import { TaskHistoryDelivery } from '@shared/types/task-inspector-activity'
function coerceDelivery(attempt: number): TaskHistoryDelivery {
  return attempt > 0 ? TaskHistoryDelivery.Retry : TaskHistoryDelivery.Initial
}

import { TaskHistoryDelivery } from '@shared/types/task-inspector-activity'
const DEL = new Set(Object.values(TaskHistoryDelivery))
function isDelivery(v: unknown): v is TaskHistoryDelivery {
  return typeof v === 'string' && DEL.has(v)
}

When it happens

Trigger: A redelivery path that forgets to set `delivery: 'retry'`, an external caller using `'retransmit'` or omitting the field, or a defaulting layer producing `undefined`.

Common situations: New retry infrastructure not setting the flag; tests building events without the delivery context; consumers bridging an external protocol without a delivery concept.

Related errors

• ${label} is not a legal task status
• kind is not a legal history event kind
• accuracy is not legal
• 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/aa1d6a3b69a902f1. Report an issue: GitHub.