Node.js in Docker Compose cannot reach MySQL on 127.0.0.1:3306
Error: connect ECONNREFUSED 127.0.0.1:3306Short 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.
Fix it fast
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'2Match what you see, then jump to its fix
- 1
ECONNREFUSED 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
Connection refused on a port such as 3307, the published host portThe app uses the published host port instead of the container portFix - 3
The first start fails and a restart worksMySQL is still initializing when the app startsFix
- 1
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 30Confirmed by docs.docker.com
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 ps2Fix
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 30Confirmed by docs.docker.com
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 202Fix
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_healthy3Verify
The app container only starts after db reports healthy.
docker compose up -d && docker compose psConfirmed by docs.docker.com
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
Related fixes
Back end
NestJS watch mode does not restart after I save a file
Changes show on the host but not in the running container
Watch mode only sees files that exist inside the process that runs it.
3 causes, each with a fixBack end
TypeORM connects but creates no tables or columns
A new column is missing, with no error at startup
TypeORM does not create tables by itself.
3 causes, each with a fixBack end
TypeScript cannot find module '@nestjs/core' or its type declarations
error TS2307: Cannot find module '@nestjs/common' or its corresponding type declarations.
TS2307 means TypeScript searched node_modules and found neither the package nor its types.
3 causes, each with a fixBack end
A Docker build or container says npm: not found
npm: command not found
A container only has the programs its image holds.
3 causes, each with a fixBack end
ECS task stops with exec format error on start
exec /usr/local/bin/docker-entrypoint.sh: exec format error
The container's binary was built for another CPU than the task runs on.
2 causes, each with a fixBack 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