Skip to content
uploy docs

Database connection errors

Where to look first

Section titled “Where to look first”
  • The app’s Logs tab — what error is the client library reporting?
  • The project’s Databases section — is the database Ready?

Common causes

Section titled “Common causes”

Database not attached

Section titled “Database not attached”
  • Symptom: DATABASE_URL is unset inside the container.
  • Fix: Create a managed Postgres, then Attach it to the app. Attachment (not creation) is what injects the URL.

App started before attachment

Section titled “App started before attachment”
  • Symptom: App started without DATABASE_URL, will not see it until restart.
  • Fix: Restart the app after attaching.

TLS required

Section titled “TLS required”
  • Symptom: SSL/TLS required or similar from the client library.
  • Fix: The injected URL includes sslmode=require. Ensure your client library honours query parameters (some require explicit config).

Quota or provisioning failure

Section titled “Quota or provisioning failure”
  • Symptom: Database stuck in Provisioning or Failed.
  • Fix: See Quota exceeded or contact support.

Restore stuck in pending

Section titled “Restore stuck in pending”
  • Symptom: After requesting a point-in-time restore, the Restore pending banner stays indefinitely and neither Promote nor Discard resolves the state.
  • What it means: uploy spawns a parallel cluster and waits for CloudNativePG to report it as ready. If the replay fails (for example, the chosen timestamp predates available WAL), the parallel cluster never becomes ready.
  • Fix: Click Discard to clear the pending state. The original database is unaffected. Then retry with a timestamp closer to the present, and confirm it falls inside the window returned by the UI’s min/max. If discard itself fails, contact support with the database ID.

If none of the above matches

Section titled “If none of the above matches”

Contact support with the project name, database name, and the client error.