"database system is starting up": the compute is waking, retry

"database system is starting up": diagnose and fix

Symptom

FATAL: the database system is starting up immediately on connection attempts.

Cause

The Neon compute is waking from idle (scale to zero) or restarting. Postgres is not ready to accept connections yet. Agents misread this as wrong credentials or a dead database and start rotating secrets.

Confirm

1. Check the compute status in the Console Branches page (Idle vs Active).
2. The error appears on fresh connects after an idle gap, then clears on its own within seconds.

Fix

• Retry with exponential backoff and jitter; the compute is usually ready in seconds.
• Raise the client's connection timeout so the wake-up fits inside it.
• If this happens on every deploy or cron run, the workload is fighting scale to zero: extend the idle timeout or disable it for that branch.

Verify

Retries succeed; no credential changes were needed. If wakes are frequent enough to matter, the timeout change eliminates them.

Neon's connection error docs (verified live 2026-09-26) cover 'Couldn't connect to compute node' including cold-start timing; the latency docs describe checking compute Active/Idle status and increasing connection timeouts to accommodate cold starts.