paperclipai/paperclip · error

The Paperclip database is not running or reachable, so the p

Error message

The Paperclip database is not running or reachable, so the pre-update backup cannot be taken. Start the service with `paperclipai service start` and retry, or skip the backup with `paperclipai update --no-backup`.

What it means

Thrown by runPreUpdateBackup when the database backup step fails with a connection-unreachable error (codes ECONNREFUSED, EHOSTUNREACH, ENETUNREACH, ETIMEDOUT, or messages matching those patterns). The pre-update backup is mandatory by default, so if the Paperclip database is down the update aborts rather than risk upgrading without a restorable snapshot. The message tells the user to either start the service or pass --no-backup.

Source

Thrown at cli/src/commands/update.ts:61

    if (typeof record.code === "string" && DATABASE_UNREACHABLE_CODES.has(record.code)) return true;
    if (typeof record.message === "string" && /\b(?:ECONNREFUSED|EHOSTUNREACH|ENETUNREACH|ETIMEDOUT)\b|connection refused/i.test(record.message)) return true;
    if (record.cause !== undefined) pending.push(record.cause);
    if (Array.isArray(record.errors)) pending.push(...record.errors);
  }
  return false;
}

async function runPreUpdateBackup(options: UpdateOptions, backup: () => Promise<void>, hasInstanceData = hasPaperclipInstanceData): Promise<void> {
  if (!hasInstanceData()) {
    const message = "Skipping the pre-update backup because this Paperclip instance has not been onboarded and has no data to back up.";
    if (options.json) console.error(message); else console.log(pc.yellow(message));
    return;
  }
  try {
    await backup();
  } catch (error) {
    if (isDatabaseUnreachableError(error)) {
      throw new Error(
        "The Paperclip database is not running or reachable, so the pre-update backup cannot be taken. Start the service with `paperclipai service start` and retry, or skip the backup with `paperclipai update --no-backup`.",
        { cause: error },
      );
    }
    throw error;
  }
}

async function restartActiveManagedService(expectedVersion: string): Promise<boolean> {
  const instanceId = resolvePaperclipInstanceId();
  const detection = await detectServiceManager({ instanceId });
  if (!detection.supported || !(await detection.manager.status()).active) return false;
  await restartManagedService({ instanceId, expectedVersion });
  return true;
}

export function detectInstallMode(executablePath = process.argv[1] ?? "", paths = resolveInstallStorePaths()): InstallMode {
  const resolved = path.resolve(executablePath || ".");

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Start the Paperclip service: `paperclipai service start`, confirm with `paperclipai service status`, then re-run the update.
2. Skip the backup if you accept the risk: `paperclipai update --no-backup`.
3. Verify DATABASE_URL resolves and the DB port is listening (`nc -zv <host> <port>`), fix connectivity, then retry.

Example fix

# before
paperclipai update
# after (DB down, accept risk)
paperclipai update --no-backup

// Confirm the DB is reachable before running update with backup
async function dbReachable(): Promise<boolean> {
  try {
    const res = await fetch(`${process.env.PAPERCLIP_API_URL ?? 'http://localhost:3100'}/api/health`);
    return res.ok;
  } catch { return false; }
}
// const opts = (await dbReachable()) ? {} : { backup: false } as UpdateOptions;

try {
  await updateCommand(options);
} catch (error) {
  if (error instanceof Error && error.message.includes('pre-update backup cannot be taken')) {
    await updateCommand({ ...options, backup: false }); // accept the risk and retry without backup
  } else throw error;
}

When it happens

Trigger: Running `paperclipai update` (or updateCommand programmatically) with backup enabled (default) on an onboarded instance whose database is not accepting connections — service stopped, wrong DATABASE_URL, firewall, or DB process crashed. isDatabaseUnreachableError walks error.cause/.errors to detect these codes.

Common situations: Database service not started after a reboot. DATABASE_URL pointing at a stale/remote host. Postgres crashed or still starting up. Network partition to a remote DB. Migrating hosts and forgetting to start `paperclipai service start`.

Related errors

• Request failed: ${response.status}
• Request failed with status ${response.status}
• Export request returned no data
• Config not found at ${configPath}.
• Config at ${configPath} does not define a database connectio

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/ca7fdd93701f7d70. Report an issue: GitHub.