Guides › HTML / PHP sites › Site down or error screens

Docker Compose: Service Cannot Connect to Database Container

Network.

Reference guide. This guide is written from established practice and the official documentation of the tools involved. We have not yet tested every step on a live demo site. Back up your site before you change anything.
Site down or error page

When an app container cannot reach its database container, the usual causes are the wrong host name, the database not being ready yet or a wrong network.

1Use the service name2Check the logs3Check credentials4Wait for readiness5Check networks6Check the port7Recreate if data is staleFixed? Test the site. If not, get help.
The steps in order. Work down the list and stop when the problem is solved.

Step 1: Use the service name

Illustration for Step 1: Use the service name

Inside Compose, the host is the service name, such as db, not localhost.

Step 2: Check the logs

Illustration for Step 2: Check the logs

Run docker compose logs db and see whether it started cleanly.

Step 3: Check credentials

Illustration for Step 3: Check credentials

User, password and database name must match what the database container was created with.

Step 4: Wait for readiness

Illustration for Step 4: Wait for readiness

Add a healthcheck and depends_on with condition: service_healthy.

Step 5: Check networks

Illustration for Step 5: Check networks

Both services must share a network. Run docker network ls.

Step 6: Check the port

Illustration for Step 6: Check the port

Use the internal port, such as 5432 or 3306, not the published one.

Step 7: Recreate if data is stale

Illustration for Step 7: Recreate if data is stale

Credentials set on first start persist in the volume.

Still stuck?

If these steps do not solve it, we fix it for you for a flat $99. Full refund if we do not solve it within 7 days.

Related guides

Did this solve it? If not, email hello@sitefixlab.org with the exact error text and we will look into it. Try the problem finder.

Last updated 2026-11-22.