Step 1: The 30-Second Fix — Check Your Connection String
Before you touch anything else, look at how you're connecting. Most “timeout” errors happen because you're pointing at the wrong host, or you've got a typo in the port. I've seen this more times than I can count—someone copies a config from a blog and forgets that their local MySQL runs on 3307, not the default 3306.
What's actually happening here is that your client sends a TCP SYN packet, the server never responds (because nothing's listening on that port), and your client waits until the OS-level connect timeout kicks in—usually 30 seconds if you didn't set one explicitly. That feels like a “connection timeout” but it's really a “connection refused” that got masked.
So, step one: verify the host, port, and database name. On Linux, you can test with nc:
nc -zv your-db-host 3306
If that hangs, you've got a network or firewall issue, not a database issue. If it returns “Connected,” move to step 2.
Also, don't forget the Unix socket path if you're on localhost with MySQL. Sometimes the TCP connection is blocked but the socket works fine. Try the socket if you're on the same machine.
Step 2: The 5-Minute Fix — Tune Your Connection Pool and Timeouts
If the connection string is fine, the next most common culprit is your connection pool running dry. What's happening here is that your app grabs a connection, never returns it, and eventually every request waits for a free connection. The error you see might say “connection timeout” but it's really “pool exhaustion timeout.”
Check your pool settings. For HikariCP (the default in Spring Boot), you want to ensure maximumPoolSize is proportional to your DB's max_connections. A common mistake is setting pool size to 200 when your DB only allows 100—your pool will throw timeouts while the DB is overloaded.
Also, look at connectionTimeout in your pool config. The default is 30 seconds, which is way too long for an app that needs fast failover. I usually set it to 3 seconds so the user gets an error instead of a frozen spinner. Example for HikariCP:
spring.datasource.hikari.connection-timeout=3000
spring.datasource.hikari.maximum-pool-size=10
For PostgreSQL's connection pool (PgBouncer or pgpool), the principle is the same: make sure pool_size and max_client_conn align with your server's limits.
But wait—there's a subtlety. If you're using a cloud DB (like RDS or Cloud SQL), the default wait_timeout on the server might be 8 hours, but your app's idle connections get killed by a proxy after 5 minutes. That's a classic AWS RDS issue: your pool thinks the connection is alive, but the server already closed it. The fix is to enable TCP keepalive on the client side and set a validationTimeout or use connection test queries. In HikariCP, set connection-test-query=SELECT 1.
If you're using MySQL, also check the server's interactive_timeout and wait_timeout. If they're set low, you'll see frequent timeouts for idle connections. You can raise them, but that's a band-aid. Better to handle reconnects in your app.
One more thing: if you're on a containerized setup (Docker, Kubernetes), check the network policy. I once spent an hour chasing a DB timeout only to find that a NetworkPolicy was dropping traffic after 60 seconds of idle. The fix was to add a keepalive or increase the idle timeout in the CNI plugin.
Step 3: The 15+ Minute Fix — Deep Dive into OS and Network
If steps 1 and 2 don't resolve it, the issue is likely at the OS or network layer. Here's where you need to look at TCP stacks and keepalive settings.
First, check the kernel's TCP keepalive parameters—both on your app server and the DB server:
sysctl net.ipv4.tcp_keepalive_time
sysctl net.ipv4.tcp_keepalive_intvl
sysctl net.ipv4.tcp_keepalive_probes
By default, tcp_keepalive_time is 7200 seconds (2 hours). That's way too long for most applications. If you have a firewall or load balancer that drops idle connections after 5 minutes, your DB connections will die silently. The fix is to lower these values to match your infrastructure's idle timeout. Something like:
sysctl -w net.ipv4.tcp_keepalive_time=60
sysctl -w net.ipv4.tcp_keepalive_intvl=10
sysctl -w net.ipv4.tcp_keepalive_probes=6
But that only affects new connections. For existing ones, you need to reload or restart your app. Also, these settings are global—so test in a staging environment first.
Another culprit: NAT timeouts. If you're behind a NAT (like in AWS VPC with a NAT gateway), idle connections get dropped after a few minutes. The TCP keepalive fix works here too, but you might need to set the keepalive interval lower than the NAT timeout.
Now, let's talk about the database server itself. If you're seeing “connection timeout” on the server side, check the server logs. For PostgreSQL, look at log_connections and log_disconnections. For MySQL, check the error log for “Aborted connection” messages. These often reveal the actual reason—like “got an error reading communication packets” which means the client vanished.
Also, check the max connections on the server. If you hit max_connections, your server won't accept new connections, and clients will time out. The fix is to either increase max_connections (but be careful with memory) or reduce the pool size on the client. I'd rather reduce pool size than push the server to its limit—you get better performance with a smaller pool that uses the server's resources efficiently.
One more advanced tip: if you're using a connection pool and still see timeouts, check for connection leaks in your code. A query that never closes its statement can hold a connection forever. Enable leak detection in HikariCP with leakDetectionThreshold—set it to 10000 (10 seconds) and you'll get a stack trace pointing to where the connection was acquired.
spring.datasource.hikari.leak-detection-threshold=10000
That's a life-saver. It'll show you exactly which line of code is holding the connection.
If you've done all this and still have timeouts, the last resort is to capture a packet trace. Use tcpdump on both ends and look for FIN or RST packets. If you see a RST, the server is actively closing the connection—check server logs. If you see nothing, it's a firewall drop.
tcpdump -i eth0 port 3306 -w db.pcap
Open the pcap in Wireshark and filter for tcp.flags.reset or tcp.analysis.flags.
The hardest part of diagnosing timeouts is that they're often intermittent—they only happen under load or after idle. So reproduce the issue with a load test (like pgbench for PostgreSQL or mysqlslap for MySQL) while monitoring with ss -s to see connection states.
What's the takeaway? Start with the simplest thing—your connection string. Then move to pool settings. If that fails, get your hands dirty with kernel parameters and packet captures. The root cause is almost always one of these three, and now you've got a systematic way to find it.
Don't forget to check the timezone on your servers—a weird one-off, but a mismatched timezone can cause an authentication timeout if your auth tokens are timestamped. I've seen it happen with JWT-based auth. Not common, but worth a quick look if everything else checks out.