Spring Boot + Docker Compose + Postgres: A Subtle Gotcha

I recently set up a small Spring Boot project using the built-in Docker Compose support to spin up a PostgreSQL container for local development. On paper, this is straightforward—there are plenty of short tutorials walking through the setup, and Spring Boot is designed to handle most of the wiring automatically.

So I expected it to “just work.”

It didn’t.

---

The Error

I kept hitting the following error when the application started:

FATAL: Password authentication failed for user "admin"

My first assumption was simple: I must have mistyped the password somewhere. But after double-checking everything, that didn’t seem to be the case.

Spring Boot’s Docker Compose integration is supposed to propagate the credentials defined in compose.yml automatically into the application’s datasource configuration. In theory, there shouldn’t be any mismatch.

---

Confusing Signals

To debug further, I added pgAdmin to the Docker Compose setup and manually brought up the containers.

From there, I was able to connect to the database without any issues using the same credentials.

That made things even more confusing:

• The database itself was accepting the credentials
• But Spring Boot was not

Even stranger, after restarting my machine and running the exact same project the next day, everything worked.

No code changes. No config changes. Just… working.

---

The Root Cause

After digging through forums and Reddit threads, I found a key insight:

Spring Boot wasn’t connecting to the Docker container at all.

It was connecting to a different PostgreSQL instance running on my machine.

At first, I thought that couldn’t be right—I hadn’t installed Postgres locally.

But then I remembered: I had installed it… inside WSL.

Sure enough:

psql --version

confirmed that a PostgreSQL server was available there.

What was happening:

• When WSL was running, the local Postgres instance was also running
• Spring Boot attempted to connect to localhost
• Instead of hitting the Docker container, it connected to the WSL-hosted Postgres
• The credentials didn’t match → authentication failure

This also explained the inconsistent behavior:

• On days I hadn’t opened WSL → Docker container worked fine
• On days I had → local Postgres intercepted the connection

---

The Fix

Once I removed the WSL Postgres installation, the issue disappeared completely.

No more authentication errors. No more inconsistency.

---

Takeaways

1. “Localhost” isn’t always what you think it is
   If you have multiple environments (Docker, WSL, local installs), you may have multiple services competing on the same port.

2. Spring Boot Docker Compose doesn’t guarantee isolation
   It helps with orchestration, but it won’t prevent your app from connecting to the wrong service if addresses overlap.

3. Inconsistent behavior is often environmental
   If something “randomly” works or fails, check what’s running on your machine—not just your code.

---

Final Thought

This was one of those issues that looked like a configuration bug but turned out to be an environment collision.

Once you know what to look for, it’s obvious.

Before that, it’s incredibly confusing.