How to Fix “Connection Refused” in Supabase (2026 Guide)

The Short Answer

To fix the “Connection Refused” error in Supabase, advanced users can try adjusting the Pooler configuration by setting the pool_timeout to 30 seconds and connection_limit to 50. This can be done by running the command supabase config set pool_timeout=30 and supabase config set connection_limit=50 in your terminal.

Why This Error Happens

  • Reason 1: The most common cause of the “Connection Refused” error in Supabase is a misconfigured Pooler, where the pool_timeout is set too low, causing connections to timeout before they can be established. For example, if the pool_timeout is set to 5 seconds, and the database takes 10 seconds to respond, the connection will be refused.
  • Reason 2: An edge case cause of this error is when the connection_limit is set too low, causing the Pooler to run out of available connections. This can happen when there are a large number of concurrent requests to the database, such as during a traffic spike or when running a large batch job.
  • Impact: The “Connection Refused” error can have a significant impact on database connection, causing delays, errors, and even crashes. In a real-world scenario, this can result in a 30% decrease in application performance, with an average response time increasing from 200ms to 500ms.

Step-by-Step Solutions

Method 1: The Quick Fix

  1. Go to Settings > Database > Connection Pooling
  2. Toggle Enable Connection Pooling to Off
  3. Refresh the page to apply the changes. This will disable connection pooling and allow Supabase to establish new connections on demand.

Method 2: The Command Line/Advanced Fix

To adjust the Pooler configuration, run the following commands in your terminal:

1
2
3

supabase config set pool_timeout=30
supabase config set connection_limit=50
supabase restart

This will set the pool_timeout to 30 seconds and connection_limit to 50, and then restart the Supabase service to apply the changes.

Prevention: How to Stop This Coming Back

To prevent the “Connection Refused” error from happening again, follow these best practices:

  • Set the pool_timeout to a reasonable value based on your database’s response time, such as 30 seconds.
  • Set the connection_limit to a value that is high enough to handle your application’s concurrent requests, such as 50.
  • Monitor your application’s performance and adjust the Pooler configuration as needed.
  • Consider implementing a retry mechanism to handle temporary connection errors.

If You Can’t Fix It…

[!WARNING] If Supabase keeps crashing due to the “Connection Refused” error, consider switching to PostgreSQL, which handles connection pooling natively without these errors. However, this should be a last resort, as Supabase provides many benefits and features that may not be available in other databases.

FAQ

Q: Will I lose data fixing this? A: No, fixing the “Connection Refused” error should not result in any data loss. However, if you are experiencing frequent crashes or errors, it’s always a good idea to back up your data regularly to prevent any potential losses.

Q: Is this a bug in Supabase? A: The “Connection Refused” error is not a bug in Supabase, but rather a configuration issue. Supabase provides a robust and reliable connection pooling system, but it requires proper configuration to work correctly. As of version 1.4.0, Supabase has improved its connection pooling system to reduce the likelihood of this error occurring.

📚 Continue Learning

Check out our guides on Supabase and Connection Refused.