Communications link failure — Spring Boot Fix

Q: Start your database server

When to use: Use this if you forgot to start MySQL/Postgres locally or your Docker container crashed.. Connection refused means nothing is listening on that port. Start the DB service.

Q: Check the port number in the URL

When to use: Use this if the DB is running, but Spring is pointing to the wrong port.. Ensure the port in your `spring.datasource.url` matches the port your database is actually listening on. MySQL defaults to 3306, Postgres to 5432.

Q: Use 'localhost' instead of '127.0.0.1' (or vice versa)

When to use: Use this if IPv6 vs IPv4 resolution is causing issues on Windows/Mac.. Sometimes 'localhost' resolves to IPv6 (::1) but the DB only listens on IPv4 (127.0.0.1). Changing the URL can force the correct protocol.

Q: Check cloud firewall / Security Groups

When to use: Use this if connecting to AWS RDS or Cloud SQL.. Cloud databases block inbound traffic by default. Ensure the security group allows inbound TCP traffic on the DB port from your app's IP address.

Q: Allow public connections in cloud DB settings

When to use: Use this if your cloud database restricts access to private networks only.. Ensure the cloud database has 'Public accessibility' enabled if you are connecting from outside its VPC.

🔴 The Error You're Seeing

Confirm this matches your console output. If it does, you're in the right place.

ERROR LOG

2026-02-18 10:15:30.812 ERROR 8842 --- [           main] com.zaxxer.hikari.pool.HikariPool        : HikariPool-1 - Exception during pool initialization.

com.mysql.cj.jdbc.exceptions.CommunicationsException: Communications link failure

The last packet sent successfully to the server was 0 milliseconds ago. The driver has not received any packets from the server.
	at com.mysql.cj.jdbc.exceptions.SQLError.createCommunicationsException(SQLError.java:174)

⚡ Quick Fix Works 80% of the time

Ensure your database server is running and the URL/port in application.properties are correct.

# Check if MySQL is running on port 3306
mysql -u root -p -h 127.0.0.1

🧠 Why this Happens

Tap to expand the deep technical explanation

Spring Boot's connection pool (HikariCP) attempted to open a TCP socket to the IP and port specified in your `spring.datasource.url`. The operating system rejected the connection because no database server was listening at that address, or a firewall blocked the connection.

The HITEC City Parking Spot Analogy:

It's like calling a friend whose phone is switched off. The network works, but because their phone isn't on, the call is instantly rejected.

🔁 How to Reproduce Confirm this is your error

Set your `spring.datasource.url` to point to an IP address where no database is running (e.g., `jdbc:mysql://192.168.1.99:3306/db`). Start your Spring Boot app.

🛠️ Solutions (5 Ways to Fix)

Solution 1✓ Most common cause

Start your database server

👉 Use this if you forgot to start MySQL/Postgres locally or your Docker container crashed.

Connection refused means nothing is listening on that port. Start the DB service.

# Start Postgres via Docker
docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=secret postgres:15

# Or start local MySQL service
sudo systemctl start mysql

Solution 2

Check the port number in the URL

👉 Use this if the DB is running, but Spring is pointing to the wrong port.

Ensure the port in your `spring.datasource.url` matches the port your database is actually listening on. MySQL defaults to 3306, Postgres to 5432.

# Wrong port (e.g., pointing to Postgres on MySQL port)
# spring.datasource.url=jdbc:postgresql://localhost:3306/mydb

# Correct port
spring.datasource.url=jdbc:postgresql://localhost:5432/mydb

Solution 3

Use 'localhost' instead of '127.0.0.1' (or vice versa)

👉 Use this if IPv6 vs IPv4 resolution is causing issues on Windows/Mac.

Sometimes 'localhost' resolves to IPv6 (::1) but the DB only listens on IPv4 (127.0.0.1). Changing the URL can force the correct protocol.

# Try changing localhost to 127.0.0.1
spring.datasource.url=jdbc:mysql://127.0.0.1:3306/mydb

Solution 4

Check cloud firewall / Security Groups

👉 Use this if connecting to AWS RDS or Cloud SQL.

Cloud databases block inbound traffic by default. Ensure the security group allows inbound TCP traffic on the DB port from your app's IP address.

# AWS RDS Security Group Inbound Rule:
# Type: MySQL/Aurora
# Port: 3306
# Source: <your-app-ip>/32

Solution 5

Allow public connections in cloud DB settings

👉 Use this if your cloud database restricts access to private networks only.

Ensure the cloud database has 'Public accessibility' enabled if you are connecting from outside its VPC.

# AWS RDS Modify Instance -> Connectivity -> Public access: Yes

📋 Version Notes

Spring Boot 2.x

Uses HikariCP as default connection pool. Throws CommunicationsException.

Spring Boot 3.x

Identical behavior, but HikariCP logs are slightly more descriptive.

🛡️ How to Prevent This Next Time

Use Docker Compose to manage your database alongside your Spring Boot app so they start and stop together. Use connection validation in Hikari (`spring.datasource.hikari.connection-test-query`).