agalwood/Motrix · error · RangeError

Observed state must be recovered

Error message

Observed state must be recovered

What it means

For `TaskHistoryEventKind.ObservedState`, `accuracy` must be `TaskHistoryAccuracy.Recovered`. ObservedState events are emitted during recovery from a coverage gap, so by definition their data is reconstructed rather than exact. Throws this `RangeError` if accuracy is `Exact`.

Source

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

        input.fromStatus !== TaskStatus.Paused ||
        !ACTIVE_RESUME_STATUSES.has(input.toStatus)
      ) {
        throw new RangeError('Resumed must transition from paused to active')
      }
      break
    case TaskHistoryEventKind.Completed:
      if (input.toStatus !== TaskStatus.Completed) {
        throw new RangeError('Completed must end in completed')
      }
      break
    case TaskHistoryEventKind.Failed:
      if (input.toStatus !== TaskStatus.Error) {
        throw new RangeError('Failed must end in error')
      }
      break
    case TaskHistoryEventKind.ObservedState:
      if (input.accuracy !== TaskHistoryAccuracy.Recovered) {
        throw new RangeError('Observed state must be recovered')
      }
      break
    case TaskHistoryEventKind.StageChanged:
      break
  }
}

export function normalizeTransferSamples(
  samples: readonly TaskTransferSample[]
): TaskTransferSample[] {
  return samples.map((sample, index) => ({
    t: assertPositiveSafeInteger(sample.t, `samples[${index}].t`),
    down: normalizeSpeed(sample.down, `samples[${index}].down`),
    up: normalizeSpeed(sample.up, `samples[${index}].up`),
    flags: (() => {
      const flags = assertNonNegativeSafeInteger(
        sample.flags,
        `samples[${index}].flags`

View on GitHub (pinned to 1a708ee577)

Solutions

1. Always set `accuracy: TaskHistoryAccuracy.Recovered` when building ObservedState events.
2. Use a dedicated builder for recovery events that hard-codes the accuracy.
3. Do not emit ObservedState during live recording — it is recovery-only.

Example fix

// before
emit({ kind: TaskHistoryEventKind.ObservedState, accuracy: TaskHistoryAccuracy.Exact, /* ... */ })
// after
emit({ kind: TaskHistoryEventKind.ObservedState, accuracy: TaskHistoryAccuracy.Recovered, /* ... */ })

if (input.kind === TaskHistoryEventKind.ObservedState)
  input.accuracy = TaskHistoryAccuracy.Recovered

When it happens

Trigger: Submitting an ObservedState event with `accuracy: 'exact'` — usually because the recovery code reused a live-event builder that defaulted to Exact, or because accuracy was not set explicitly.

Common situations: New recovery code paths that forget to flag the event as recovered; tests reusing a live-event fixture for a recovered scenario.

Related errors

• ${label} is not a legal task status
• kind is not a legal history event kind
• toStatus is required
• Added must not have a fromStatus
• Started must enter an active status

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