paperclipai/paperclip · error · Error

Managed worktree repair requires an embedded PostgreSQL targ

Error message

Managed worktree repair requires an embedded PostgreSQL target.

What it means

backupWorktreeReseedTarget(), used by the worktree repair flow (worktreeRepairCommand), only knows how to back up an embedded PostgreSQL target: it starts the embedded cluster via ensureEmbeddedPostgres and runs runDatabaseBackup against it. If the worktree config's database.mode is anything other than 'embedded-postgres' (e.g. an external Postgres via URL), it refuses rather than guess how to back up an external database.

Source

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

      );
    }
    p.outro(
      pc.green(
        `Imported ${applied.insertedProjects} projects (${applied.insertedProjectWorkspaces} workspaces), ${applied.insertedIssues} issues, ${applied.insertedComments} comments, ${applied.insertedDocuments} documents (${applied.insertedDocumentRevisions} revisions, ${applied.mergedDocuments} merged), and ${applied.insertedAttachments} attachments into ${company.issuePrefix}.`,
      ),
    );
  } finally {
    await targetHandle.stop();
    await sourceHandle.stop();
  }
}

async function backupWorktreeReseedTarget(input: {
  targetConfig: PaperclipConfig;
  targetPaths: WorktreeLocalPaths;
}): Promise<string> {
  if (input.targetConfig.database.mode !== "embedded-postgres") {
    throw new Error("Managed worktree repair requires an embedded PostgreSQL target.");
  }
  const targetHandle = await ensureEmbeddedPostgres(
    input.targetConfig.database.embeddedPostgresDataDir,
    input.targetConfig.database.embeddedPostgresPort,
  );
  try {
    const adminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${targetHandle.port}/postgres`;
    await ensurePostgresDatabase(adminConnectionString, "paperclip");
    const result = await runDatabaseBackup({
      connectionString: `postgres://paperclip:paperclip@127.0.0.1:${targetHandle.port}/paperclip`,
      backupDir: path.resolve(input.targetPaths.backupDir, "repair"),
      retention: { dailyDays: 30, weeklyWeeks: 12, monthlyMonths: 12 },
      filenamePrefix: `${input.targetPaths.instanceId}-pre-repair`,
      backupEngine: "auto",
      includeMigrationJournal: true,
    });
    return formatDatabaseBackupResult(result);
  } finally {

View on GitHub (pinned to a7e689b3c3)

Solutions

Reconfigure the worktree to database.mode 'embedded-postgres' before running repair
Or skip managed repair and back up / repair the external database with your own tooling (pg_dump, WAL archiving)
Or recreate the worktree so it uses the embedded database the repair path expects

Example fix

# before (paperclip.config.json)
"database": { "mode": "postgres", "url": "postgres://host:5432/paperclip" }

# after
"database": {
  "mode": "embedded-postgres",
  "embeddedPostgresDataDir": "./data/pglite-or-pgdata",
  "embeddedPostgresPort": 5433
}

Defensive patterns

Strategy: validation

Validate before calling

const config = readWorktreeConfig(configPath);
if (config.database.mode !== 'embedded-postgres') {
  throw new Error('Managed repair supports embedded-postgres targets only; back up the external DB yourself.');
}
await worktreeRepairCommand(opts);

Prevention

Standardize worktrees on embedded-postgres if you rely on managed repair
Maintain your own backup strategy (pg_dump/WAL) for external-database worktrees

When it happens

Trigger: Running `paperclipai worktree repair` on a worktree whose paperclip config sets database.mode to a non-embedded value (external Postgres connection).

Common situations: Worktree originally created against a shared/external Postgres; config edited to point at an external database; repair attempted on instances managed outside the embedded-postgres lifecycle.

Related errors

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