paperclipai/paperclip · error · Error

Seed implementation returned without required validation evi

Error message

Seed implementation returned without required validation evidence.

What it means

After the seed implementation callback completes, the runner requires three pieces of evidence on the returned details: snapshotAt, migrationRevision, and validation. If any is missing, the seed cannot be marked verified, so the attempt fails with this invariant error. This is an internal contract between runWorktreeSeedAttempt and the seed implementation — a stock healthy run always populates all three.

Source

Thrown at cli/src/commands/worktree.ts:2185

      seedMode: input.seedMode,
      preserveLiveWork: input.preserveLiveWork,
      expectedCompanyId: input.expectedCompanyId,
      onPhase: (phase, status, message) => {
        activePhase = phase;
        updateWorktreeSeedManifest({
          configPath: input.configPath,
          phase,
          status,
          state: "running",
          message,
          ...(phase === "snapshot" && status === "started"
            ? { snapshotAt: new Date().toISOString() }
            : {}),
        });
      },
    });
    if (!details.snapshotAt || !details.migrationRevision || !details.validation) {
      throw new Error("Seed implementation returned without required validation evidence.");
    }
    updateWorktreeSeedManifest({
      configPath: input.configPath,
      phase: "complete",
      status: "succeeded",
      state: "verified",
      snapshotAt: details.snapshotAt,
      migrationRevision: details.migrationRevision,
      message:
        `Verified ${details.validation.companyCount} company record(s), `
        + `${details.validation.issueCount} issue record(s), auth, admin, membership, and migration state.`,
    });
    return details;
  } catch (error) {
    updateWorktreeSeedManifest({
      configPath: input.configPath,
      phase: activePhase,
      status: "failed",

View on GitHub (pinned to 01ad858492)

Solutions

Re-run the seed (worktree ensure-seeded / reseed) — a transient interruption is the most common cause
If it reproduces, collect the manifest diagnostics and report it as a Paperclip bug; do not paper over a seed marked verified without evidence
If you run a customized seed implementation, make sure it returns snapshotAt, migrationRevision, and the validation summary

Defensive patterns

Strategy: retry

Try / catch

try {
  await runWorktreeSeedAttempt(...);
} catch (error) {
  console.error(formatWorktreeSeedFailureDiagnostic(error)); // includes phase diagnostics
  throw error;
}

Prevention

Re-run the seed once before investigating; transient early returns are the common cause
If you customize the seed implementation, enforce the return contract (snapshotAt + migrationRevision + validation) with tests

When it happens

Trigger: The seed implementation returned early or via a code path that skipped the snapshot, the migration-revision resolution, or the database validation — an interrupted/aborted seed callback that still resolved, a bug in a customized seed implementation, or a future code path that omits validation evidence.

Common situations: Hacking a custom or partial seed pipeline that skips validation; a code regression where a branch returns before evidence is collected; resources exhausted mid-run causing a soft early return.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-08-21). Data as JSON: /api/errors/d2bf756c52d555a8. Report an issue: GitHub.