UnsatisfiedDependencyException: Error creating bean with name 'dockerComposeConnectionDetailsFactory'

Q: Start Docker Desktop

When to use: Use this if you intend to use the Docker Compose integration.. Ensure the Docker daemon is running and accessible from your terminal.

Q: Disable Docker Compose integration

When to use: Use this if you are managing your database manually or running in production.. Tell Spring Boot to stop trying to read and start `docker-compose.yml`.

Q: Move docker-compose.yml out of the root

When to use: Use this if you want to keep the file but don't want Spring Boot to see it.. Spring Boot only scans the project root for the file. Moving it to a subfolder hides it from the auto-configuration.

Q: Fix docker-compose.yml syntax

When to use: Use this if Docker is running but the bean still fails.. Run `docker-compose up` manually in the terminal. If it throws syntax errors, fix them. Spring Boot uses the same parser.

Q: Set lifecycle management to start-only

When to use: Use this if the app crashes when shutting down because it tries to kill the container.. Change the lifecycle management so Spring Boot starts the container but doesn't try to stop it on exit.

🔴 The Error You're Seeing

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

ERROR LOG

2026-02-20 17:20:18.300 ERROR 8842 --- [           main] o.s.boot.SpringApplication               : Application run failed

org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'dataSource' defined in class path resource ... Unsatisfied dependency expressed through parameter 0; nested exception is org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'dockerComposeConnectionDetailsFactory' defined in class path resource

⚡ Quick Fix Works 80% of the time

Ensure Docker Desktop is running, or disable Spring Boot's Docker Compose integration.

# application.properties
spring.docker.compose.enabled=false

🧠 Why this Happens

Tap to expand the deep technical explanation

Spring Boot 3.1+ has built-in Docker Compose support. If it finds a `docker-compose.yml` in your project root, it tries to start the containers automatically. If Docker isn't installed, the daemon isn't running, or the compose file has syntax errors, the `dockerComposeConnectionDetailsFactory` bean fails, crashing the app.

The HITEC City Parking Spot Analogy:

It's like an architect trying to build a house, but the concrete truck (Docker) hasn't arrived. The architect stops working because they can't pour the foundation.

🔁 How to Reproduce Confirm this is your error

Add a `docker-compose.yml` file to your project root defining a Postgres database. Close Docker Desktop. Run your Spring Boot 3.1+ app.

🛠️ Solutions (5 Ways to Fix)

Solution 1✓ Most common cause

Start Docker Desktop

👉 Use this if you intend to use the Docker Compose integration.

Ensure the Docker daemon is running and accessible from your terminal.

# Check Docker status
docker info

Solution 2

Disable Docker Compose integration

👉 Use this if you are managing your database manually or running in production.

Tell Spring Boot to stop trying to read and start `docker-compose.yml`.

# application.properties
spring.docker.compose.enabled=false

Solution 3

Move docker-compose.yml out of the root

👉 Use this if you want to keep the file but don't want Spring Boot to see it.

Spring Boot only scans the project root for the file. Moving it to a subfolder hides it from the auto-configuration.

mv docker-compose.yml ./docker/docker-compose.yml

Solution 4

Fix docker-compose.yml syntax

👉 Use this if Docker is running but the bean still fails.

Run `docker-compose up` manually in the terminal. If it throws syntax errors, fix them. Spring Boot uses the same parser.

docker-compose -f docker-compose.yml up

Solution 5

Set lifecycle management to start-only

👉 Use this if the app crashes when shutting down because it tries to kill the container.

Change the lifecycle management so Spring Boot starts the container but doesn't try to stop it on exit.

spring.docker.compose.lifecycle-management=start-only

📋 Version Notes

Spring Boot 2.x

No built-in Docker Compose support. Does not throw this error.

Spring Boot 3.x

Auto-configures Docker Compose integration if the file is present.

🛡️ How to Prevent This Next Time

If using Docker Compose integration, ensure your CI/CD pipeline has the Docker daemon running before the Spring Boot app starts.