Connection Problems

If Stack2X can't connect to your Supabase instance, or if an existing connection stops working, this guide will help you diagnose and fix the problem.

Connection Timeout

What it looks like: "Connection timed out" or "Unable to reach instance"

What it means: Stack2X tried to connect to your instance but didn't get a response in time. This is one of the most common connection issues and can have several causes.

How to fix it:

• Check that your Supabase instance is running. For Cloud instances, visit your Supabase dashboard to make sure the project isn't paused. Paused projects need to be resumed before Stack2X can connect.
• For self-hosted instances, verify that your database server is running and accessible.
• Try the connection again -- temporary network issues between Stack2X and your instance can cause occasional timeouts that resolve on their own.

Invalid Credentials

What it looks like: "Authentication failed" or "Invalid credentials"

What it means: The credentials Stack2X is using to connect don't match what the instance expects. This applies to self-hosted instances using manual credentials.

How to fix it:

• Double-check the database host, port, and password in your instance settings. Even a small typo can cause authentication to fail.
• Verify that the database user hasn't been deleted or had its password changed. If someone updated the database password, you'll need to update the credentials in Stack2X to match.
• Make sure you're using the correct service role key. You can find this in your Supabase project's API settings.

Firewall and Network Issues

What it looks like: "Connection refused" or "Network unreachable"

What it means: Something between Stack2X and your instance is blocking the connection. This is most common with self-hosted instances behind firewalls or private networks.

How to fix it:

• Add Stack2X's IP addresses to your firewall's allowlist. You can find the current list of IPs on the connection settings page in Stack2X.
• Check that your database port (usually 5432) is open and accessible from external networks.
• If your instance is on a private network or VPN, make sure there's a route for Stack2X's servers to reach it. You may need to set up a reverse proxy or bastion host.

Self-Hosted SSL Problems

What it looks like: "SSL handshake failed" or "Certificate verification error"

What it means: Stack2X requires SSL for secure connections, but your self-hosted instance's SSL certificate isn't being accepted. This can happen with self-signed certificates, expired certificates, or misconfigured SSL settings.

How to fix it:

• If you're using a self-signed certificate, toggle the Allow Self-Signed Certificates option in your instance's connection settings within Stack2X.
• Check that your SSL certificate hasn't expired. Expired certificates are a common cause of sudden connection failures that worked fine before.
• Verify that your server's SSL configuration includes the full certificate chain. Missing intermediate certificates can cause verification errors even when the certificate itself is valid.

Testing Connectivity

Stack2X includes a built-in connection test you can run at any time:

1. Go to the instance's settings page in Stack2X.
2. Click Test Connection.
3. Stack2X checks DNS resolution, network reachability, authentication, and SSL -- then reports the results.

The test results tell you exactly where the connection fails, which helps you narrow down the issue. For example, if DNS resolution succeeds but authentication fails, you know the network path is fine and the problem is with your credentials.

If the built-in test passes but backups or migrations still fail, the issue might not be the connection itself. Check Common Migration Errors for other causes.