What causes "workflow eval delegation checkpoint is missing" in paperclipai/paperclip?

Confirm the checkpoint store was configured with a persistent directory and that the same store instance backs both delegation and restore.

paperclipai/paperclip · error

workflow eval delegation checkpoint is missing

Error message

workflow eval delegation checkpoint is missing

What it means

restoreAfterDelegatedChild suspends the current session and then attempts to load the saved checkpoint for the parent session (before.sessionId) from the store. If the store returns null — no checkpoint was persisted under that id — the executor throws this error, because restoring the parent's delegated state is impossible without the checkpoint.

Source

Thrown at packages/paperclip-runner/src/eval/live-workflow-executor.ts:305

  store: CapabilityLiveSessionStore;
  transportOptions: CapabilityLiveSessionServiceOptions["transportOptions"];
}): Promise<{
  service: CapabilityLiveSessionService;
  session: CapabilityLiveSession;
} | null> {
  const before = input.session.snapshot();
  const advanced = await advanceDelegationReturnMockState({
    mockState: before.mockState,
    parentRunId: before.authority.runId,
    parentSessionId: before.sessionId,
    parentTaskId: before.authority.taskId,
    capabilities: before.authority.capabilities,
  });
  if (advanced === null) return null;
  await input.session.suspend("workflow eval delegated child completed");
  const checkpoint = await input.store.load(before.sessionId);
  if (checkpoint === null) {
    throw new Error("workflow eval delegation checkpoint is missing");
  }
  const {
    providerRunBinding: _providerRunBinding,
    ...checkpointWithoutBinding
  } = checkpoint;
  const at = new Date().toISOString();
  const updated: CapabilityLiveSessionSnapshot = {
    ...checkpointWithoutBinding,
    revision: checkpoint.revision + 1,
    updatedAt: at,
    authority: {
      ...checkpoint.authority,
      runId: advanced.returnRunId,
    },
    mockState: advanced.mockState,
    stateHistory: [
      ...(checkpoint.stateHistory ?? []),
      {

View on GitHub (pinned to 01ad858492)

Solutions

Confirm the checkpoint store was configured with a persistent directory and that the same store instance backs both delegation and restore.
Check that before.sessionId is the id actually used when the checkpoint was saved (log both).
Save the checkpoint before suspending/spawning the delegated child if the save path may be skipped.
Re-run the eval from the start if checkpoints were removed; or make restore tolerant by re-deriving parent state when the checkpoint is absent.

Example fix

// before
const checkpoint = await input.store.load(before.sessionId);
if (checkpoint === null) throw new Error('workflow eval delegation checkpoint is missing');
// after
const checkpoint = await input.store.load(before.sessionId);
if (checkpoint === null) {
  await input.store.save(before.sessionId, buildCheckpointFromSnapshot(before)); // re-derive instead of throwing
}

Defensive patterns

Strategy: try-catch

Validate before calling

const checkpoint = await input.store.load(before.sessionId);
if (checkpoint === null) throw new Error(`checkpoint for session ${before.sessionId} not persisted before delegation`);

Type guard

async function hasCheckpoint(store: CheckpointStore, sessionId: string): Promise<boolean> {
  return (await store.load(sessionId)) !== null;
}

Try / catch

try {
  await executor.restoreAfterDelegatedChild(/* ... */);
} catch (err) {
  if ((err as Error).message === 'workflow eval delegation checkpoint is missing') {
    logger.error({ sessionId: before.sessionId }, 'checkpoint lost; re-running delegation');
    return rerunDelegation(before);
  }
  throw err;
}

Prevention

Use a persistent checkpoint store directory shared across the whole eval process lifetime.
Save the checkpoint before suspending or spawning the delegated child.
Never delete checkpoint files while an eval run is active.
Log sessionId at both save and load time to catch id drift.

When it happens

Trigger: A delegated child completes and triggers restore, but input.store.load(before.sessionId) returns null because the checkpoint was never saved, was deleted, the store points at a different backend/directory, or the sessionId changed between delegation and restore.

Common situations: Ephemeral/in-memory store reset between phases of the eval; pointing the store at the wrong data directory after a config change; a crash or cleanup job removing checkpoints mid-run; resuming an eval run across process restarts with a non-persistent store.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/923a114c91045b19. Report an issue: GitHub.