paperclipai/paperclip · error · Error

Workspace database repair command failed during ${repairPhas

Error message

Workspace database repair command failed during ${repairPhase}.

What it means

Thrown when the repair reseed child process exits with a non-zero code without a timeout — the CLI itself failed. The route reads <worktree>/.paperclip/seed-manifest.json to extract the persisted seedFailurePhase (manifest.state === "failed" with a string phase), reports it via operation progress, and throws this message naming the outer repair phase (target_backup or full_reseed). Full child stdout/stderr is captured in the workspace operation for diagnosis.

Source

Thrown at server/src/routes/execution-workspaces.ts:776

              try {
                const failedManifest = JSON.parse(readFileSync(manifestPath, "utf8")) as {
                  phase?: unknown;
                  state?: unknown;
                };
                seedFailurePhase = failedManifest.state === "failed" && typeof failedManifest.phase === "string"
                  ? failedManifest.phase
                  : null;
              } catch {
                // The outer repair phase remains exact when no seed phase was persisted.
              }
              await reportProgress({
                metadata: { seedFailurePhase },
                system: seedFailurePhase ? `Workspace seed failed during ${seedFailurePhase}.\n` : null,
              });
              throw new Error(
                repairCommandTimedOut
                  ? `Workspace database repair command timed out during ${repairPhase}.`
                  : `Workspace database repair command failed during ${repairPhase}.`,
              );
            }
            if (!reseedObserved) {
              await reportRepairPhase("target_backup", "succeeded");
              await reportRepairPhase("full_reseed", "started");
            }

            const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as Record<string, unknown>;
            if (!isVerifiedWorktreeSeedManifest(manifest)) {
              throw new Error("Workspace reseed returned without a verified terminal manifest.");
            }
            const expectedInstanceId = resolveManagedWorkspaceInstanceId(workspaceCwd);
            if (manifest.targetInstanceId !== expectedInstanceId) {
              throw repairPreconditionError(
                422,
                "seed_manifest_instance_mismatch",
                "Verified seed manifest belongs to a different workspace instance.",
              );

View on GitHub (pinned to a7e689b3c3)

Solutions

Read the workspace operation's captured stdout/stderr and the seedFailurePhase metadata — the CLI's own phase (e.g. source_open, target_backup) pinpoints the failure.
Open <worktree>/.paperclip/seed-manifest.json and check state/phase/attemptId for the CLI-side failure detail.
Fix the named phase: stop services holding locks on the base database, free disk space, or correct a company-id mismatch by re-registering the base.
Retry the repair action; the target is backed up and the worktree files are preserved, so re-runs are safe.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await repair(id);
} catch (err) {
  const op = await api.listWorkspaceOperations(id).then((ops) => ops.at(-1));
  const phase = op?.metadata?.repairDiagnostics?.at(-1)?.phase ?? op?.metadata?.seedFailurePhase;
  // route remediation by phase: source_open → fix/stop base DB locks; target_backup → free disk; etc.
}

Prevention

Stop services and agents holding locks on the base .paperclip database before repairing.
Watch the workspace operation's captured stdout/stderr immediately after a failed repair — the CLI's own phase is recorded in metadata.seedFailurePhase.
Keep disk headroom for the --backup-target copy of the target database.

When it happens

Trigger: POST repair where the spawned cli worktree reseed exits non-zero: source database corrupt or locked, target backup cannot be written (disk full), instance/company identity checks inside the CLI fail (PAPERCLIP_SEED_EXPECTED_COMPANY_ID mismatch), or the source config passed via --from-config is invalid. Any non-zero exit that is not the 20-minute timeout produces this error.

Common situations: Base .paperclip database locked by a running service during repair; PAPERCLIP_SEED_EXPECTED_COMPANY_ID env injected by the route not matching the source DB (company migrated/re-seeded); disk exhaustion during target backup; a worktree target whose .paperclip was left in a state the CLI refuses to overwrite without the expected flags.

Related errors

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