koala73/worldmonitor · error · Error

[_finalizeWaveRun] no run ${runId}

Error message

[_finalizeWaveRun] no run ${runId}

What it means

Internal invariant guard in _finalizeWaveRun: no waveRuns row exists for the supplied runId. The tier advance and lease clear cannot proceed because the run record is missing — a caller logic bug, or the row was deleted mid-finalize.

Source

Thrown at convex/broadcast/waveRuns.ts:1409

 *   - waveRuns.status MUST be 'broadcast-created' (or 'sent' for idempotency
 *     on a duplicate finalize — returns no-op success without re-advancing
 *     the tier)
 *   - broadcastRampConfig.pendingRunId MUST === runId
 *
 * Without these, two concurrent finalizes could both advance currentTier
 * (skipping a wave's worth of progress) AND both clear the lease.
 */
export const _finalizeWaveRun = internalMutation({
  args: {
    runId: v.string(),
    sentAt: v.number(),
  },
  handler: async (ctx, { runId, sentAt }) => {
    const run = await ctx.db
      .query("waveRuns")
      .withIndex("by_runId", (q) => q.eq("runId", runId))
      .unique();
    if (!run) throw new Error(`[_finalizeWaveRun] no run ${runId}`);

    // Status check FIRST — broadcastId presence is downstream of being in
    // broadcast-created status. Checking presence before status would mask
    // a wrong-status caller behind a misleading "missing broadcastId" error.
    if (run.status === "sent") {
      // Idempotent: a duplicate finalize on an already-sent run is a no-op,
      // not an error. Don't re-advance the tier.
      return { ok: true as const, alreadySent: true as const, advancedToTier: undefined };
    }
    if (run.status !== "broadcast-created") {
      throw new Error(
        `[_finalizeWaveRun] run ${runId} is ${run.status}, expected broadcast-created`,
      );
    }
    if (!run.broadcastId || !run.segmentId) {
      throw new Error(
        `[_finalizeWaveRun] run ${runId} missing broadcastId/segmentId`,
      );

View on GitHub (pinned to eeab0a219f)

Solutions

1. Verify the runId passed by finalizeWaveAction matches the claimed run
2. Manually reconcile ramp tier state (the wave was sent; check Resend) before restarting the ramp

When it happens

Trigger: Thrown at convex/broadcast/waveRuns.ts:1409 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of koala73/worldmonitor@eeab0a219f (2026-08-21). Data as JSON: /api/errors/dc1e90e3d7732b91. Report an issue: GitHub.