Failed to restore ${basename(opts.backupFile)} with psql: ${

Error message

Failed to restore ${basename(opts.backupFile)} with psql: ${sanitizeRestoreErrorMessage(error)}

What it means

Error "Failed to restore ${basename(opts.backupFile)} with psql: ${sanitizeRestoreErrorMessage(error)}" thrown in paperclipai/paperclip.

Source

Thrown at packages/db/src/backup-lib.ts:1001

    if (existsSync(sqlFile)) {
      try { unlinkSync(sqlFile); } catch { /* ignore */ }
    }
    throw error;
  } finally {
    await closeSql();
  }
}

export async function runDatabaseRestore(opts: RunDatabaseRestoreOptions): Promise<void> {
  const connectTimeout = Math.max(1, Math.trunc(opts.connectTimeoutSeconds ?? 5));
  let psqlRestoreError: unknown = null;
  try {
    await restoreWithPsql(opts, connectTimeout);
    return;
  } catch (error) {
    psqlRestoreError = error;
    if (!(await hasStatementBreakpoints(opts.backupFile))) {
      throw new Error(
        `Failed to restore ${basename(opts.backupFile)} with psql: ${sanitizeRestoreErrorMessage(error)}`,
      );
    }
  }

  const sql = postgres(opts.connectionString, { max: 1, connect_timeout: connectTimeout });

  try {
    await sql`SELECT 1`;
    for await (const statement of readRestoreStatements(opts.backupFile)) {
      await sql.unsafe(statement).execute();
    }
  } catch (error) {
    const statementPreview = typeof error === "object" && error !== null && typeof (error as Record<string, unknown>).query === "string"
      ? String((error as Record<string, unknown>).query)
        .split(/\r?\n/)
        .map((line) => line.trim())
        .find((line) => line.length > 0 && !line.startsWith("--"))

View on GitHub (pinned to 120ae5428f)

Solutions

Inspect the sanitized psql error, fix the database/backup issue, and retry the restore.
Verify the backup file is a valid plain-SQL dump for this database.

When it happens

Trigger: Thrown at packages/db/src/backup-lib.ts:1001 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@120ae5428f (2026-08-18). Data as JSON: /api/errors/97bd3609a215d42e. Report an issue: GitHub.