diegosouzapw/OmniRoute · error

[BATCH] Stale batch has no item checkpoints; failing…

Error message

[BATCH] Stale batch ${batch.id} has no item checkpoints; failing instead of replaying provider calls

What it means

Stale-batch recovery guard: a batch left mid-run (crash/restart) has request counters implying external provider calls may already have happened (total/completed/failed > 0 or status finalizing) but zero item checkpoints exist to know which items were processed. Replaying would duplicate provider calls (double billing/side effects), so the batch is failed explicitly instead of recovered.

Solutions

1. Accept the failed status and resubmit the batch as a new job if duplication is acceptable.
2. Ensure item checkpoints are flushed synchronously (or before external calls) so future crashes are recoverable.
3. Investigate why checkpoints were lost — checkpoint writes must precede provider calls.

When it happens

Trigger: Thrown at open-sse/services/batchProcessor.ts:118 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of diegosouzapw/OmniRoute@a179ffed5b (2026-08-25). Data as JSON: /api/errors/a62afa3cb56d4519. Report an issue: GitHub.

Appendix: source

Thrown at open-sse/services/batchProcessor.ts:118

    } else if (batch.status === "cancelling") {
      await cancelBatch(batch);
    }
  }

  // Cleanup task: delete files for batches completed more than completionWindow ago
  await cleanupExpiredBatches();
}

function recoverStaleBatch(batch: BatchRecord): void {
  const checkpointCount = countBatchItemCheckpoints(batch.id);
  const hasPotentialExternalEffects =
    batch.requestCountsTotal > 0 ||
    batch.requestCountsCompleted > 0 ||
    batch.requestCountsFailed > 0 ||
    batch.status === "finalizing";

  if (checkpointCount === 0 && hasPotentialExternalEffects) {
    console.warn(
      `[BATCH] Stale batch ${batch.id} has no item checkpoints; failing instead of replaying provider calls`
    );
    failBatch(
      batch.id,
      "Cannot safely recover stale batch because item checkpoints are unavailable; create a new batch to retry intentionally."
    );
    return;
  }

  console.log(`[BATCH] Recovering stale batch ${batch.id} (${batch.status}) → validating`);

  if (batch.outputFileId) {
    deleteFile(batch.outputFileId);
  }
  if (batch.errorFileId) {
    deleteFile(batch.errorFileId);
  }

View on GitHub (pinned to a179ffed5b)