Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Node.js in Docker Compose cannot reach MySQL on 127.0.0.1:3306

ErrorError: connect ECONNREFUSED 127.0.0.1:3306

Short answer

Inside a container, 127.0.0.1 is that container, not MySQL. Set the database host to the Compose service name and use port 3306, the container port, not the published host port. If the error stays at first start, MySQL is still initializing: add a healthcheck and make the app wait for service_healthy.

  • Applies to Docker Compose v2, MySQL 8.4 image, Node.js 22, TypeORM 0.3.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the host and port the app container is really using, from inside the container.

    docker compose exec app printenv | grep -i -E 'DB_|MYSQL|DATABASE'
  2. 2Match what you see, then jump to its fix

    1. 1ECONNREFUSED 127.0.0.1:3306 on every start, even when MySQL is upThe app connects to 127.0.0.1 or localhost instead of the service nameFix
    2. 2Connection refused on a port such as 3307, the published host portThe app uses the published host port instead of the container portFix
    3. 3The first start fails and a restart worksMySQL is still initializing when the app startsFix

What does the error look like?

  • Error: connect ECONNREFUSED 127.0.0.1:3306

Cause 1 of 3

The app connects to 127.0.0.1 or localhost instead of the service name

1Check

The Compose networking docs say each service registers its name with an internal DNS server, so one service reaches another by that name.

docker compose config | grep -n -i -E 'host|services:|mysql|db:'

2Fix

Use the MySQL service name as host.

services:
  db:
    image: mysql:8.4
  app:
    environment:
      DB_HOST: db
      DB_PORT: "3306"

3Verify

Restart the app and read its log.

docker compose up -d --force-recreate app && docker compose logs app --tail 30

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

The app uses the published host port instead of the container port

1Check

The docs say service-to-service traffic uses the container port, and the host port is only for access from outside the network.

docker compose ps

2Fix

With a mapping like 3307:3306, the host uses 3307 and the other containers use 3306.

db:
  ports:
    - "3307:3306"
app:
  environment:
    DB_PORT: "3306"

3Verify

The app logs a successful connection.

docker compose logs app --tail 30

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

MySQL is still initializing when the app starts

1Check

The MySQL image page says the server does not accept connections until its first-start initialization finishes. The Compose docs add that depends_on waits until a container runs, not until it is ready.

docker compose logs db --tail 20

2Fix

Give MySQL a healthcheck and make the app depend on it being healthy.

db:
  image: mysql:8.4
  healthcheck:
    test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
    interval: 5s
    timeout: 5s
    retries: 20
app:
  depends_on:
    db:
      condition: service_healthy

3Verify

The app container only starts after db reports healthy.

docker compose up -d && docker compose ps

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Read the database host and port from environment variables, never hard-code localhost in Compose projects.
  • Use a healthcheck on every database service.
  • Keep a separate .env for running the app on the host and for running it in Compose.

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

Back end

NestJS GraphQL cannot work out the output type of a field or query

Cannot determine a GraphQL output type for the "<name>". Make sure your class is decorated with an appropriate decorator.

In code-first mode Nest reads TypeScript types through decorators, and arrays, promises and unions disappear at runtime.

2 causes, each with a fix

Next step

Want this handled for good?

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