paperclipai/paperclip · error

database_unreachable

database_unreachable

Error message

database_unreachable

What it means

The health endpoint's SELECT 1 database probe threw; the database is unreachable, and the unhealthy response still carries workspace readiness info so an operator can distinguish a half-finished restore from a dead database.

Source

Thrown at server/src/routes/health.ts:305

              commit,
              ...(cloud ? { cloud } : {}),
              ...(hiddenSettings.length ? { hiddenSettings } : {}),
            },
      );
      return;
    }

    try {
      await db.execute(sql`SELECT 1`);
    } catch (error) {
      logger.warn({ err: error }, "Health check database probe failed");
      // Carry readiness on the unhealthy response too: the seed phase recorded on
      // disk is exactly what tells an operator whether this is a half-finished
      // restore or a database that died after being verified.
      const workspace = exposeWorkspaceReadiness
        ? await resolveWorkspaceReadiness({ db, handoffSubject }).catch(() => null)
        : null;
      res.status(503).json({
        status: "unhealthy",
        version: serverVersion,
        serverVersion,
        commit,
        error: "database_unreachable",
        ...(exposeFullDetails ? { serverInfo } : {}),
        ...(workspace ? { workspace } : {}),
        ...(cloud ? { cloud } : {}),
      });
      return;
    }

    let bootstrapStatus: "ready" | "bootstrap_pending" = "ready";
    let bootstrapInviteActive = false;
    // Cloud-managed instances have no first-admin concept: the control
    // plane owns identity and its trusted-header users are deliberately
    // never instance_admin, so the role-count gate below would report
    // bootstrap_pending forever and lock every managed tenant out at the

View on GitHub (pinned to 01ad858492)

Solutions

1. Check the health/connectivity of the backing service (database, dev server supervisor, storage), fix the underlying fault, and retry.

When it happens

Trigger: Thrown at server/src/routes/health.ts:176 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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