Database Not Ready

database-not-ready · 503

The database woke but didn't accept a connection in time, so the API opened no tunnel rather than hand out a port that answers nothing.

timeoutSeconds is how long the API waited, 30 seconds by default. The wake itself went through, so the database is awake for the next try.

Besides the members every error carries, this type adds service, environment and timeoutSeconds.

Common causes

  • PostgreSQL took longer than usual to accept connections after it woke.
  • Redis didn't answer a ping in time.

How to fix the call

  • Run the same command again: this is one of the errors where retrying unchanged is right.
  • If it keeps failing, tell the user: the database may be failing to start.

Example response

json
{
  "type": "database-not-ready",
  "title": "Database Not Ready",
  "detail": "orders-db woke but did not accept a connection within 30 s in staging. Try again.",
  "service": "orders-db",
  "environment": "staging",
  "timeoutSeconds": 30,
  "requestId": "req-1785231000000-4f7b2c9ae",
  "timestamp": "2026-07-28T09:30:00.000Z",
  "path": "/v1/services/0199e0a3-6f21-7c4a-9d18-2b7c5f3ad401/tunnels",
  "method": "POST",
  "instance": "POST /v1/services/0199e0a3-6f21-7c4a-9d18-2b7c5f3ad401/tunnels",
  "status": 503,
  "docs": "https://ghaym.me/docs/errors/database-not-ready"
}