What causes "[_recordPoolFilterStats] no run ${args.runId}" in koala73/worldmonitor?

Trace the runId in the calling action (pickWaveAction) back to the value returned by _claimWaveRunLease — they must be identical.

koala73/worldmonitor · error · Error

[_recordPoolFilterStats] no run ${args.runId}

Error message

[_recordPoolFilterStats] no run ${args.runId}

What it means

Thrown by the _recordPoolFilterStats internal mutation when no waveRuns row matches the provided runId via the by_runId index with .unique(). Per its own docstring, this is NOT a normal recovery scenario — it indicates a logic bug in the caller (pickWaveAction), since the run row is created by _claimWaveRunLease before pool selection begins.

Source

Thrown at convex/broadcast/waveRuns.ts:466

 * them for THIS run's pool selection remains useful even if the lease has
 * since rotated. Throws only if the run row itself is missing (a logic
 * bug in the caller, not a normal recovery scenario).
 */
export const _recordPoolFilterStats = internalMutation({
  args: {
    runId: v.string(),
    excludeNonEnglish: v.boolean(),
    eligiblePoolCount: v.number(),
    excludedCount: v.number(),
    excludedLocaleCounts: v.record(v.string(), v.number()),
  },
  handler: async (ctx, args) => {
    const run = await ctx.db
      .query("waveRuns")
      .withIndex("by_runId", (q) => q.eq("runId", args.runId))
      .unique();
    if (!run) {
      throw new Error(`[_recordPoolFilterStats] no run ${args.runId}`);
    }
    await ctx.db.patch(run._id, {
      excludeNonEnglish: args.excludeNonEnglish,
      eligiblePoolCount: args.eligiblePoolCount,
      excludedCount: args.excludedCount,
      excludedLocaleCounts: args.excludedLocaleCounts,
      updatedAt: Date.now(),
    });
    return { ok: true as const };
  },
});

// ───────────────────────────────────────────────────────────────────────────
// Pick phase
// ───────────────────────────────────────────────────────────────────────────

/**
 * Acquire the wave-run lease atomically. Refuses if:

View on GitHub (pinned to ffec79ac33)

Solutions

Trace the runId in the calling action (pickWaveAction) back to the value returned by _claimWaveRunLease — they must be identical.
Check whether discardWaveRun or a manual DB delete removed the row mid-flight; if so, this throw is benign and the run should be treated as cancelled.
If calling from a test, first insert a waveRuns row with that runId, or call through _claimWaveRunLease to create one.

Defensive patterns

Strategy: validation

Prevention

In pickWaveAction, only call _recordPoolFilterStats with the runId returned by _claimWaveRunLease — never a derived or stale value.
Do not run discardWaveRun concurrently with an in-flight pickWaveAction.
In tests, insert a waveRuns row with the runId before calling _recordPoolFilterStats directly.

When it happens

Trigger: pickWaveAction calls runMutation('_recordPoolFilterStats', {runId}) with a runId that was never claimed, was already discarded via discardWaveRun, or has a typo/transcription error. A race where the run was force-deleted between lease acquisition and stat recording.

Common situations: A developer modifies pickWaveAction and passes the wrong runId variable. The operator ran discardWaveRun while pickWaveAction was still executing. A test invokes _recordPoolFilterStats directly with a fabricated runId.

Related errors

AI-assisted analysis of koala73/worldmonitor@ffec79ac33 (2026-08-12). Data as JSON: /api/errors/5643b86c7f3a237b. Report an issue: GitHub.