Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

The MongoDB container in Docker Compose never turns healthy

Errorthe container is reported as unhealthy in docker ps

Short 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.

  • Applies to Docker Compose 2.20, Docker Engine 27, mongo image 8.0
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 db
  2. 2Match what you see, then jump to its fix

    1. 1The probe output shows an error from your test command instead of a ping resultThe check calls the old mongo shellFix
    2. 2The probe output reports an authentication or authorization errorAuthentication is on and the check does not log inFix
    3. 3The 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

What does the error look like?

  • the container is reported as unhealthy in docker ps
  • services 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.yaml

2Fix

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: 30s

3Verify

Bring the stack up and wait for the health state to change.

docker compose up -d
docker compose ps

Confirmed by hub.docker.com

Did this fix it?

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_INITDB

2Fix

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 db

Confirmed by hub.docker.com

Did this fix it?

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 50

2Fix

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: 40s

3Verify

Start from an empty volume and watch the status settle.

docker compose down -v
docker compose up -d
docker compose ps

Confirmed by docs.docker.com

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.