The MongoDB container in Docker Compose never turns healthy
the container is reported as unhealthy in docker psShort answer
A mongo healthcheck usually fails because the command inside it is wrong, not because MongoDB is down. Images from mongo 6 on ship mongosh, not mongo. If you enabled the root user, a check that needs login fails too. Give slow first starts a start_period, then read the stored health output.
Fix it fast
1Find out which cause you have
Docker keeps the output of the last health probes. Read them, because they show the real error of your test command.
docker inspect db2Match what you see, then jump to its fix
- 1
The probe output shows an error from your test command instead of a ping resultThe check calls the old mongo shellFix - 2
The probe output reports an authentication or authorization errorAuthentication is on and the check does not log inFix - 3
The container goes unhealthy during the first minute, and healthy later if you re-check by handThe probe runs before MongoDB is ready and the retries run outFix
- 1
What does the error look like?
the container is reported as unhealthy in docker psservices that wait on service_healthy never start
Cause 1 of 3
The check calls the old mongo shell
1Check
The mongo image documentation uses mongosh as the client and says mongo is the command only for 4.x. Look at the test line in your compose file.
grep -n -A6 healthcheck compose.yaml2Fix
Call mongosh and run a ping.
services:
db:
image: mongo:8
healthcheck:
test: ["CMD", "mongosh", "--quiet", "--eval", "db.runCommand({ ping: 1 })"]
interval: 10s
timeout: 5s
retries: 5
start_period: 30s3Verify
Bring the stack up and wait for the health state to change.
docker compose up -d
docker compose psConfirmed by hub.docker.com
Cause 2 of 3
Authentication is on and the check does not log in
1Check
Setting both MONGO_INITDB_ROOT_USERNAME and MONGO_INITDB_ROOT_PASSWORD starts mongod with authentication enabled. A check that runs a command needing a login then fails.
docker compose config | grep -n MONGO_INITDB2Fix
Pass the credentials and the authentication database to mongosh, the same way the image documentation logs in.
healthcheck:
test: ["CMD", "mongosh", "--quiet", "-u", "mongoadmin", "-p", "secret",
"--authenticationDatabase", "admin", "--eval", "db.runCommand({ ping: 1 })"]3Verify
Recreate the container and check its status.
docker compose up -d --force-recreate db
docker compose ps dbConfirmed by hub.docker.com
Cause 3 of 3
The probe runs before MongoDB is ready and the retries run out
1Check
Failed probes during start_period do not count toward retries, but the default start period is 0s, with 3 retries at a 30s interval.
docker compose logs db --tail 502Fix
Add a start_period that covers a normal first start, and keep retries above 3.
healthcheck:
test: ["CMD", "mongosh", "--quiet", "--eval", "db.runCommand({ ping: 1 })"]
interval: 10s
timeout: 5s
retries: 5
start_period: 40s3Verify
Start from an empty volume and watch the status settle.
docker compose down -v
docker compose up -d
docker compose psConfirmed by docs.docker.com
How do I stop it coming back?
- Use mongosh in every script, healthcheck and init file that targets mongo 6 or newer.
- Run the exact test command by hand inside the container before you put it in the compose file.
- Make dependent services wait with depends_on and condition: service_healthy; the short form does not wait for health.
- Keep credentials in an env file rather than writing them into the compose file.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Servers
Docker Compose starts container B before container A is healthy
health status: unhealthy
Compose does not wait for a container to be ready, only for it to be running.
3 causes, each with a fixServers
apk cannot find py-pip in an Alpine Docker image
py-pip (no such package):
On current Alpine releases there is no package called py-pip.
2 causes, each with a fixServers
ng serve runs in the container but localhost:4200 does not open
The browser cannot open localhost:4200 although ng serve is running in the container
ng serve listens on localhost by default, which inside a container is the container itself.
3 causes, each with a fixServers
Angular routes return 404 from nginx when you refresh or open a link
The home page loads, but refreshing /some/route shows an nginx 404
Angular routes like /users/42 are not files, so nginx looks for them on disk and returns 404.
3 causes, each with a fixServers
AH00558: Apache in Docker cannot reliably determine its fully qualified domain name
Set the 'ServerName' directive globally to suppress this message
AH00558 is a warning, not a crash.
2 causes, each with a fixServers
Apache in a Docker container logs AH01114 when it proxies to a backend
AH01114: HTTP: failed to make connection to backend: api
Apache's proxy worker could not open a connection to the address in ProxyPass.
5 causes, each with a fix