Connection refused: connect — 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 the OS rejected the connection because 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.

🔴 The Error You're Seeing

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

ERROR LOG

2026-02-14 16:10:40.100 ERROR 8842 --- [           main] com.zaxxer.hikari.pool.HikariPool        : HikariPool-1 - Exception during pool initialization.

java.net.ConnectException: Connection refused: connect
	at java.base/sun.nio.ch.Net.connect0(Native Method)
	at com.zaxxer.hikari.pool.HikariPool.newConnection(HikariPool.java:345)

⚡ Quick Fix Works 80% of the time

Ensure your database server (MySQL/Postgres) is running and the port in application.properties matches.

# Check if DB is running on default port
# application.properties
spring.datasource.url=jdbc:postgresql://localhost:5432/mydb

🧠 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 at that address actively refused the connection because no database server was listening there.

The HITEC City Parking Spot Analogy:

It is 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

Point spring.datasource.url at a database that is not running (or a wrong port), then start the app. HikariCP logs java.net.ConnectException: Connection refused during pool initialization.

🛠️ Solutions (3 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 the OS rejected the connection because 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

📋 Version Notes

Spring Boot 2.x

Uses HikariCP as default connection pool. Throws HikariPool initialization error.

Spring Boot 3.x

Identical behavior, but HikariCP logs are slightly more detailed.

🛡️ How to Prevent This Next Time

Use Docker Compose to manage your database alongside your Spring Boot app so they start and stop together.