Most connection errors are one of six things, in a specific order. Work down the ladder instead of guessing, and you'll usually find the break in a few minutes, whatever client you're using.
No credit card. 14 days. Cancel in one click.
Quick answer: Connection failures almost always break at one of six points, in order: DNS (can't resolve the hostname), network (can't reach the port), SSL (certificate or mode mismatch), login (wrong credentials or auth method), database (the database or warehouse doesn't exist or isn't running), or permissions (you're in, but can't do what you're trying to do). Check them in that order and you'll usually find the actual problem fast.
A raw driver error like "connection refused" or "SSL error" tells you almost nothing about where in the chain things actually broke. The fix is to check the chain in order, DNS, then network, then SSL, then login, then database, then permissions, because each step assumes the one before it worked. If DNS is broken, don't waste time debugging SSL settings. This is the same ladder QueryFlow's own connection diagnostics walk through automatically when a connection fails, and it works the same in QueryFlow, psql, DBeaver, or anything else.
If the hostname doesn't resolve, nothing after this matters. Test it directly:
nslookup your-db-host.example.com
Common causes: a typo in the hostname, a private/internal hostname that only resolves on a corporate VPN you're not connected to, or a hostname that changed after a database migration and your connection settings weren't updated. If you're working from home and the host only resolves on your office network, connect your VPN before anything else.
DNS resolving doesn't mean the port is reachable. A firewall, security group, or IP allowlist can block the connection even when the hostname resolves fine. Test with:
nc -zv your-db-host.example.com 5432
(Swap 5432 for your actual port, 3306 for MySQL, 5439 for Redshift, 443 for most cloud warehouse APIs.) A hang or refusal here usually means one of: your IP isn't on the database's allowlist (add it, or ask whoever manages the warehouse to), you're behind a VPN that's required but not connected, or the port is simply wrong because you copied it from a different environment.
Once the port is reachable, SSL handshake failures are next. The most common one on Postgres and Postgres-compatible databases is an sslmode mismatch, your client is set to disable when the server requires SSL, or set to verify-full when the server's certificate doesn't match what verify-full expects. Try:
psql "host=your-db-host.example.com port=5432 dbname=postgres sslmode=require"
If that connects but verify-full doesn't, the issue is almost always a certificate chain problem, not something wrong with your credentials. Managed database providers (RDS, Cloud SQL, Supabase) usually document exactly which sslmode to use, worth checking rather than guessing.
Now you're actually talking to the database, and it's rejecting who you say you are. This is usually a wrong password, an expired token (Snowflake PATs and OAuth tokens both expire), or the wrong auth method entirely, trying username/password against a database that now requires a personal access token or OAuth. Regenerate the credential if it's expired, and double-check you're using the auth method the database actually expects today, not the one it expected a year ago when the connection was first set up.
Credentials accepted, but the specific database or warehouse you named doesn't exist, is misspelled, or, in the case of Snowflake or Redshift, is currently suspended or paused. Check the exact name (case matters more often than people expect) and confirm the warehouse or cluster is actually running, not just that the account exists.
You're connected and authenticated, and now a specific query or action fails with a permissions error. This is a role or grant problem, not a connection problem. On Postgres and Redshift that means checking GRANT statements for the role you're using; on Snowflake it means checking the role assigned to your user has USAGE and SELECT on the right warehouse, database, and schema. A worked fix on Postgres:
GRANT USAGE ON SCHEMA analytics TO reporting_role; GRANT SELECT ON ALL TABLES IN SCHEMA analytics TO reporting_role;
If someone else administers the database, this is the point where you stop debugging alone and ask them to check the grants, rather than continuing to guess at connection settings that were never the problem.
QueryFlow's connection diagnostics walk this exact ladder automatically when a connection fails, stopping at the first broken link and explaining the likely fix in plain language, with options to copy the details, save a log, or report the problem directly. It doesn't replace knowing the ladder, but it does save you the manual step-by-step above.
Say you're trying to connect to a Redshift cluster from home and get a generic timeout. DNS resolves fine (nslookup returns an address), so that's not it. The network check with nc hangs, no response at all. That points at the network step: either the cluster's security group doesn't allow your current IP, or your home network is blocking outbound traffic on that port, which is rarer but happens on some corporate laptops with strict firewall policies. You add your current IP to the cluster's inbound rule, and it connects. No SSL, login, or permissions issue existed, they never got the chance to, because the connection never made it past the network step. That's the whole point of checking in order: you didn't spend twenty minutes tweaking sslmode settings for a problem that was actually a security group.
Database drivers sometimes report the wrong step. A Postgres "password authentication failed" error can occasionally really be an SSL negotiation problem that the driver mislabels as a login failure once it gives up. If you're confident your password is right and login still fails, double back to the SSL step before assuming your credentials themselves are wrong. This is exactly the kind of misdirection the ladder approach protects against: work it in order and you'll usually catch a mislabeled error by process of elimination, even when the tool's own message points you somewhere slightly wrong.
Usually an expired credential (tokens and OAuth grants expire on a schedule you don't control) or a change on the server side, a maintenance window, an IP allowlist update, or a paused warehouse. Work the ladder from the top; it'll usually point to login or network.
Some managed providers require a specific SSL mode beyond require, like verify-ca or verify-full, and reject a plain require. Check your provider's connection docs for the exact mode they expect.
Usually the client is using different connection defaults, a different port, a different sslmode, or it's not picking up a VPN or proxy your terminal session already has active. Compare the exact connection string both are using.
No, only if the host is on a private network that requires one. Test DNS resolution first; if the hostname simply doesn't resolve without your VPN connected, that's your answer.
No, it applies to any SQL client. QueryFlow's connection diagnostics just walk it automatically and explain each step, but the underlying troubleshooting order works the same in psql, DBeaver, or anything else.
Work the ladder, and try QueryFlow's built-in diagnostics next time one comes up. 14-day free trial, no card.
No credit card. 14 days. Cancel in one click.