ruvnet/ruflo · error

Checkpoint not found: ${checkpointId}

Error message

Checkpoint not found: ${checkpointId}

What it means

Thrown by LongRunningWorker#resumeFromCheckpoint (v3/@claude-flow/integration/src/long-running-worker.ts:455) when storage.load(checkpointId) resolves to null/undefined — the checkpoint store has no entry with that id. Ids look like `cp_${workerId}_${taskId}_${sequence}`, so a mismatch in any component yields not-found.

Source

Thrown at v3/@claude-flow/integration/src/long-running-worker.ts:455

      checkpointId: checkpoint.id,
      sequence: checkpoint.sequence,
      progress: checkpoint.progress,
    });

    return checkpoint;
  }

  /**
   * Resume execution from a checkpoint
   *
   * @param checkpointId - Checkpoint ID to resume from
   * @returns Agent output with results
   */
  async resumeFromCheckpoint(checkpointId: string): Promise<AgentOutput> {
    const checkpoint = await this.storage.load(checkpointId);

    if (!checkpoint) {
      throw new Error(`Checkpoint not found: ${checkpointId}`);
    }

    this.emit('resuming-from-checkpoint', {
      workerId: this.id,
      checkpointId,
      taskId: checkpoint.taskId,
      progress: checkpoint.progress,
    });

    // Restore state
    this.currentState = { ...checkpoint.state };
    this.checkpointSequence = checkpoint.sequence;
    this.checkpoints = await this.storage.list(checkpoint.taskId, this.id);

    // Create a synthetic task from checkpoint
    const resumeTask: Task = {
      id: checkpoint.taskId,
      type: 'resume',

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. List available checkpoints (via the storage layer / any list API) and match by taskId+workerId to recover the correct id before resuming.
2. Use a durable checkpoint storage backend when resuming across process restarts, and verify the id exists right before resume.
3. Treat this error as 'restart task from scratch': catch it and fall back to executing the task normally.
4. Persist the last checkpoint id at task-submission time so the resume path never guesses.

Example fix

// before
const out = await worker.resumeFromCheckpoint(lastKnownId); // may be gone

// after
const cp = await worker.storage.load(lastKnownId);
if (!cp) {
  // no checkpoint survived: re-run the task from the beginning
  out = await worker.execute(task);
} else {
  out = await worker.resumeFromCheckpoint(lastKnownId);
}

const cp = await worker.storage.load(checkpointId);
if (!cp) {
  // fall back to fresh execution
  return worker.execute(task);
}
return worker.resumeFromCheckpoint(checkpointId);

async function checkpointExists(storage: { load(id: string): Promise<Checkpoint | null> }, id: string): Promise<boolean> {
  return (await storage.load(id)) != null;
}

try {
  return await worker.resumeFromCheckpoint(id);
} catch (e) {
  if (/^Checkpoint not found:/.test((e as Error).message)) {
    return worker.execute(task); // restart from scratch
  }
  throw e;
}

When it happens

Trigger: Resuming with an id from a different worker or task; resuming after the checkpoint store was cleared (in-memory storage lost on restart, expired entries in a TTL store); typos or truncated ids (very long ids clipped in logs); sequence numbers shifting after a restart reset checkpointSequence.

Common situations: Process restarted expecting durable checkpoints but storage is in-memory; resuming from a persisted job spec after the store rotated; multi-instance deployments where the checkpoint lives on another instance's storage.

Related errors

• No active task to checkpoint
• hexToBytes: odd-length hex string
• SSRF guard: only HTTPS URLs are permitted, got ${parsed.prot
• SSRF guard: private/loopback host rejected — ${host}
• SSRF guard: invalid URL — ${rawUrl}

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/48cbcf925865ca8f. Report an issue: GitHub.