A Supabase connection error can come from a provider incident, a full connection pool, or the way your application connects. Start with current Supabase status and the official status page. Match the affected service, region and incident time to your project. An operational provider indicator does not prove that your project is healthy.
Keep the exact error and connection method
Record the timestamp and timezone, project region, failing function and exact error text. Separate direct Postgres connections, pooler connections, REST requests, Auth and Realtime symptoms. Note whether the problem started with a deployment or an increase in traffic. Keep passwords, database URLs containing credentials, API keys and user data out of public reports.
| Symptom | Check next |
|---|---|
max_client_conn | The pooler's client limit and application connection count |
too many clients already | Database connections, including pools opened by each application instance |
| A statement timeout | Logs for the query, role and time of failure |
| A direct connection fails from one runtime | That runtime's IP support and the selected connection method |
| HTTP 5xx errors or slow REST requests | Project resource use and logs for the affected request |
| An official incident matches your project | The notice's affected service, region and latest update |
The first two errors need different checks. Supabase's HTTP and connection troubleshooting guide distinguishes pooler-client exhaustion from Postgres connection exhaustion. It also identifies project resource pressure and expensive queries as possible causes of API timeouts and 5xx errors. A restart may relieve symptoms temporarily; it does not resolve the underlying connection demand.
Count clients and database connections separately
A pooler's client limit counts callers connected to that pooler. Its backend pool size controls connections it can open to Postgres. Direct connections and both poolers' backend connections share the database's overall budget, alongside Supabase's own services. Increasing pool size therefore does not automatically solve client exhaustion and can consume remaining database capacity. See connection pooling and limits.
Inspect Database Connections and the relevant pooler-client report in Observability. Those reports show their last refresh rather than a live count. Compare the timestamps with the failure. Review application pool settings across all replicas, including overlapping deployments, before changing capacity. Do not assume a per-process pool size is your whole application's connection count.
Confirm the endpoint fits your runtime
Copy the endpoint and username from the project's Connect dialog. Do not construct the pooler hostname from the region or reuse a direct-connection username without checking the selected mode.
Direct Postgres connections use IPv6 unless the project has the IPv4 add-on. An IPv4-only persistent backend can use the shared pooler in session mode. For serverless workloads, Supabase recommends transaction pooling, but that mode has prepared-statement and session-state limitations. Check your driver's compatibility before switching. These choices apply to Postgres clients; a browser using the Data API follows a different path. Consult Supabase's connection-method guide.
Investigate timeouts without masking them
A slow query and a failed attempt to obtain a connection require different evidence. Match the error to database logs and the role executing the query. Supabase's Query Performance view covers slow queries that completed; it does not list timed-out queries. Use the logs for those failures, as described in its timeout documentation. Review query behavior before increasing a timeout globally.
After a correction, verify the affected function with a read-only check and watch its error rate. For a failed write, confirm the original operation's outcome before retrying it. A homepage loading is not proof that database writes, login and subscriptions have all recovered.
When escalating, send a redacted error example, timestamps, connection mode, project region and relevant logs through private support. Treat a matching provider notice as evidence about its stated scope, not an explanation for every project error.
Follow Supabase provider alerts or review Supabase incident history.