{"record":{"id":"ca7fdd93701f7d70","repo":"paperclipai/paperclip","slug":"the-paperclip-database-is-not-running-or-reachable","errorCode":null,"errorMessage":"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`.","messagePattern":"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`\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/src/commands/update.ts","lineNumber":61,"sourceCode":"    if (typeof record.code === \"string\" && DATABASE_UNREACHABLE_CODES.has(record.code)) return true;\n    if (typeof record.message === \"string\" && /\\b(?:ECONNREFUSED|EHOSTUNREACH|ENETUNREACH|ETIMEDOUT)\\b|connection refused/i.test(record.message)) return true;\n    if (record.cause !== undefined) pending.push(record.cause);\n    if (Array.isArray(record.errors)) pending.push(...record.errors);\n  }\n  return false;\n}\n\nasync function runPreUpdateBackup(options: UpdateOptions, backup: () => Promise<void>, hasInstanceData = hasPaperclipInstanceData): Promise<void> {\n  if (!hasInstanceData()) {\n    const message = \"Skipping the pre-update backup because this Paperclip instance has not been onboarded and has no data to back up.\";\n    if (options.json) console.error(message); else console.log(pc.yellow(message));\n    return;\n  }\n  try {\n    await backup();\n  } catch (error) {\n    if (isDatabaseUnreachableError(error)) {\n      throw new Error(\n        \"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`.\",\n        { cause: error },\n      );\n    }\n    throw error;\n  }\n}\n\nasync function restartActiveManagedService(expectedVersion: string): Promise<boolean> {\n  const instanceId = resolvePaperclipInstanceId();\n  const detection = await detectServiceManager({ instanceId });\n  if (!detection.supported || !(await detection.manager.status()).active) return false;\n  await restartManagedService({ instanceId, expectedVersion });\n  return true;\n}\n\nexport function detectInstallMode(executablePath = process.argv[1] ?? \"\", paths = resolveInstallStorePaths()): InstallMode {\n  const resolved = path.resolve(executablePath || \".\");","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/cli/src/commands/update.ts#L43-L79","documentation":"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.","triggerScenarios":"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.","commonSituations":"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`.","solutions":["Start the Paperclip service: `paperclipai service start`, confirm with `paperclipai service status`, then re-run the update.","Skip the backup if you accept the risk: `paperclipai update --no-backup`.","Verify DATABASE_URL resolves and the DB port is listening (`nc -zv <host> <port>`), fix connectivity, then retry."],"exampleFix":"# before\npaperclipai update\n# after (DB down, accept risk)\npaperclipai update --no-backup","handlingStrategy":"validation","validationCode":"// Confirm the DB is reachable before running update with backup\nasync function dbReachable(): Promise<boolean> {\n  try {\n    const res = await fetch(`${process.env.PAPERCLIP_API_URL ?? 'http://localhost:3100'}/api/health`);\n    return res.ok;\n  } catch { return false; }\n}\n// const opts = (await dbReachable()) ? {} : { backup: false } as UpdateOptions;","typeGuard":null,"tryCatchPattern":"try {\n  await updateCommand(options);\n} catch (error) {\n  if (error instanceof Error && error.message.includes('pre-update backup cannot be taken')) {\n    await updateCommand({ ...options, backup: false }); // accept the risk and retry without backup\n  } else throw error;\n}","preventionTips":["Always confirm `paperclipai service status` is healthy before running update.","In CI/automation, pass --no-backup explicitly when you accept the risk, or pre-check DB connectivity.","Keep the database service enabled at boot so it is reachable after restarts."],"tags":["backup","database","network","update"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}