Three Healthy Docker Containers. One Broken Application

You have spent more than an hour setting up Docker Compose for your new project. It might be a three-tier application with Nginx, a Node.js API, and MySQL — or anything really. You run docker compose up, watch the logs scroll past, and see all three containers in the running state.

Docker Desktop confirms it. Everything is green.

You open the browser and hit the API endpoint. It fails.

You check the logs:

1Error: connect ECONNREFUSED 127.0.0.1:3306

The database, API, and Nginx are all running. But the application is broken, and nothing in the error message tells you why.

This is what most beginners face while working on tasks like deploying a three-tier application via Docker Compose and making all containers communicate with each other.

In this article we will walk you through the entire thing — how to set up proper communication between containers, how to troubleshoot Docker networking issues, and how to prevent this error from ever happening again.

Let's Rebuild the Incident

Let's build a minimal e-commerce API called ShopWave. The communication architecture is simple:

1Browser
2  ↓
3Nginx (port 80)
4  ↓
5Node.js API (port 3000)
6  ↓
7MySQL (port 3306)

This API exposes a single endpoint: GET /products. It connects to MySQL on startup. If the connection fails, the process exits.

The project structure:

1shopwave/
2├── docker-compose.yml
3├── api/
4│   ├── Dockerfile
5│   ├── package.json
6│   └── index.js
7├── nginx/
8│   └── nginx.conf
9└── mysql/
10    └── init.sql

Setting Up the Three-Tier Application

Here is the initial setup exactly as many developers write it the first time.

docker-compose.yml

1services:
2  nginx:
3    image: nginx:alpine
4    ports:
5      - "80:80"
6    volumes:
7      - ./nginx/nginx.conf:/etc/nginx/conf.d/default.conf
8    depends_on:
9      - api
10
11  api:
12    build: ./api
13    environment:
14      DB_HOST: localhost
15      DB_PORT: 3306
16      DB_USER: root
17      DB_PASSWORD: shopwave
18      DB_NAME: shopwave
19    depends_on:
20      - mysql
21
22  mysql:
23    image: mysql:8.0
24    environment:
25      MYSQL_ROOT_PASSWORD: shopwave
26      MYSQL_DATABASE: shopwave
27    volumes:
28      - ./mysql/init.sql:/docker-entrypoint-initdb.d/init.sql

api/index.js

1const express = require('express');
2const mysql = require('mysql2');
3
4const app = express();
5
6const db = mysql.createConnection({
7  host: process.env.DB_HOST,
8  port: process.env.DB_PORT,
9  user: process.env.DB_USER,
10  password: process.env.DB_PASSWORD,
11  database: process.env.DB_NAME,
12});
13
14db.connect((err) => {
15  if (err) {
16    console.error('[DB] Connection failed:', err.message);
17    process.exit(1);
18  }
19  console.log('[DB] Connected to MySQL successfully');
20});
21
22app.get('/products', (req, res) => {
23  db.query('SELECT * FROM products', (err, results) => {
24    if (err) return res.status(500).json({ error: err.message });
25    res.json(results);
26  });
27});
28
29app.listen(3000, () => console.log('[API] Running on port 3000'));

mysql/init.sql

1CREATE TABLE IF NOT EXISTS products (
2  id   INT AUTO_INCREMENT PRIMARY KEY,
3  name VARCHAR(255) NOT NULL
4);
5
6INSERT INTO products (name) VALUES ('Laptop'), ('Mouse'), ('Keyboard');

nginx/nginx.conf

1server {
2  listen 80;
3
4  location / {
5    proxy_pass http://api:3000;
6  }
7}

Now spin everything up:

1docker compose up --build

The screenshot below shows all three containers in the running state.

Troubleshooting the Bug

Did you spot the bug in the compose file above?

Look at this section:

1environment:
2  DB_HOST: localhost

This is the bug. If you are new to Docker Compose you might feel it is correct and reasonable. You connect to MySQL using localhost all the time in local development. Why would Docker be any different?

Run this to see all container statuses:

1docker ps

Everything looks healthy. Now hit the API:

1curl http://localhost/products

You will get a 502 Bad Gateway from Nginx because the API request fails. Or the API container exits immediately. Check the logs:

1docker logs shopwave-api

We know all container services are up and running. But the API cannot reach the database.

Why Was This Happening?

Before understanding the answer, let's go through the questions most engineers ask at this point.

"Is MySQL actually running?"

1docker ps

Yes. The MySQL container is Up.

"Are the ports wrong?"

Review the docker-compose.yml. MySQL is not even exposing a host port — it doesn't need to, since the API is supposed to talk to it internally. The configuration looks correct.

"Is there a startup race condition?"

Possibly, but depends_on is set. And the error says ECONNREFUSED, not a timeout. Something is actively refusing the connection.

"Is it a credentials issue?"

No — ECONNREFUSED means the TCP connection was rejected before authentication even started.

"Is Docker networking broken?"

1docker network ls

Docker created a network called shopwave_default. The containers are on it.

1docker network inspect shopwave_default

Every container has its own IP address on the network. Docker networking is functioning fine.

So what is wrong here?

The Hidden Truth About localhost Inside a Container

Here is what most Docker tutorials skip past without explaining it clearly.

Inside a container, localhost refers to that container — and only that container.

Not the host machine. Not Docker Desktop. Not other containers. Just itself.

This is because each container has its own isolated network namespace. Think of it as every container being its own tiny computer with its own loopback interface.

1API Container
2  localhost → 127.0.0.1 → API Container itself
3
4MySQL Container
5  localhost → 127.0.0.1 → MySQL Container itself

So when the API tries to connect to localhost:3306, it is looking for MySQL running inside the API container itself. There is no MySQL there. Port 3306 is not open. The OS-level TCP stack says: connection refused.

MySQL is running — just in a completely different network namespace that localhost inside the API container cannot see.

This is the mental model shift that makes everything else make sense.

How Docker DNS Actually Works

So how are containers supposed to talk to each other?

When you use Docker Compose, it automatically creates a bridge network and registers every service on that network using its service name as a DNS hostname.

The service name in your docker-compose.yml:

1services:
2  mysql:   # ← this name becomes a DNS hostname
3    image: mysql:8.0

Inside any container on the same Compose network, the hostname mysql resolves directly to the MySQL container's IP address.

Docker has a built-in DNS server running on every bridge network. When the API container looks up mysql, Docker DNS intercepts the query and returns the correct container IP — no manual configuration, no /etc/hosts editing, no static IPs.

1API Container
2  mysql → Docker DNS → 172.20.0.2 (MySQL Container IP)

You can verify this from inside a running container:

1docker exec -it shopwave-api sh
2nslookup mysql

It resolves. The DNS is working. The network is working. The only problem was the code using localhost instead of mysql.

The One-Word Fix

One word change. Open docker-compose.yml and update the environment variable:

1environment:
2  DB_HOST: mysql    # ← was: localhost
3  DB_PORT: 3306
4  DB_USER: root
5  DB_PASSWORD: shopwave
6  DB_NAME: shopwave

Restart the stack:

1docker compose down
2docker compose up --build

Now test it:

1curl http://localhost/products

1[
2  { "id": 1, "name": "Laptop" },
3  { "id": 2, "name": "Mouse" },
4  { "id": 3, "name": "Keyboard" }
5]

The API connects. The data comes back. Everything works.

How Docker Bridge Networking Works

Now that the fix is in place, let's understand what Docker is doing underneath.

When you run docker compose up, Docker creates a bridge network for your project:

1shopwave_default (bridge network)
2├── nginx    → 172.20.0.4
3├── api      → 172.20.0.3
4└── mysql    → 172.20.0.2

A bridge network is a virtual switch inside the Docker host. Containers connected to the same bridge can reach each other directly — using their container IP addresses, or using their service names via Docker DNS.

Containers on the same bridge network:

• Can reach each other by service name (mysql, api, nginx)
• Communicate on container ports, not host ports
• Are isolated from containers on other networks

Docker Port Mapping Misconception

When you write:

1ports:
2  - "80:80"

This means: map host port 80 to container port 80.

This is for external access — letting traffic from your laptop or the internet reach a container.

It has nothing to do with container-to-container communication.

When Nginx proxies to the API, it does not go through host port 3000. It goes directly through the bridge network to the API container's internal port 3000.

1# Correct
2proxy_pass http://api:3000;   ← container port, service name
3
4# Wrong
5proxy_pass http://localhost:3000;              ← localhost inside nginx container
6proxy_pass http://host.docker.internal:3000;   ← unnecessary for same-network containers

If you publish a port (3000:3000) for a container and then use that host port from another container, you're routing traffic out of Docker, through the host machine, and back in — completely unnecessary when both containers are on the same bridge.

Common Docker Networking Mistakes

Mistake 1: Using localhost between containers

1# Wrong
2DB_HOST: localhost
3
4# Correct
5DB_HOST: mysql   # use the service name

localhost inside a container is that container's own loopback. It never reaches another container.

Mistake 2: Using host ports for internal communication

1# Wrong
2proxy_pass http://localhost:3000;
3
4# Correct
5proxy_pass http://api:3000;

Service names work directly on bridge networks. Host ports are for external access only.

Mistake 3: Using the wrong container port

1# Wrong
2DB_PORT: 3360   # typo, wrong port
3
4# Correct
5DB_PORT: 3306   # the port MySQL listens on inside its container

When communicating between containers, always use the container's internal port — not a remapped host port.

Mistake 4: Trusting container health as application health

1docker ps → all containers Up

A container being Up means the process inside it started. It does not mean your application is correctly wired together. Misconfigured environment variables, wrong service names, or missing network connections can all cause application failures even when every container shows as healthy.

Quick Command Reference

1# View all Docker networks
2docker network ls
3
4# Inspect a specific network — see which containers are on it
5docker network inspect shopwave_default
6
7# Inspect a container's full networking config
8docker inspect shopwave-api
9
10# Test DNS from inside a running container
11docker exec -it shopwave-api sh
12nslookup mysql
13ping mysql
14
15# View live logs for a specific container
16docker logs -f shopwave-api
17
18# View running containers
19docker ps
20
21# Create a custom network manually
22docker network create app-network
23
24# Connect an existing container to a network
25docker network connect app-network nginx
26
27# Disconnect a container from a network
28docker network disconnect app-network nginx

Summary

We fixed the issue with a one-word change — replacing localhost with mysql.

But the real lesson wasn't the fix.

Docker wasn't broken. The containers were healthy. The application failed because the code was built on an assumption that doesn't hold inside containers: that localhost is a shared address that everything on the same machine can see.

Inside a container, each process lives in its own isolated network namespace. localhost belongs only to that namespace — not to Docker, not to the host machine, and not to the other containers running beside it.

Once that assumption changes, Docker networking stops feeling like a black box. You stop asking:

"Why is Docker broken?"

and start asking the right question:

"Which hostname should this service be using to reach that service?"

More often than not, the answer is simply the service name.

And the next time your containers look healthy but your application doesn't, ask yourself one more question:

"Am I talking to the right service?"

That single question can save you hours of debugging.

Frequently Asked Questions

Why can't Docker containers communicate with each other?

Containers often fail to communicate because of incorrect hostnames, isolated network namespaces, or misunderstanding how Docker networks work. In many cases, using localhost instead of the service name is the root cause.

Does localhost refer to the host machine in Docker?

No. Inside a container, localhost refers only to that container itself. It does not point to the host machine or other containers.

How does Docker DNS work?

Docker automatically provides an internal DNS service that allows containers on the same network to discover each other using their service or container names. No configuration is required — it works out of the box with Docker Compose.

Should containers communicate using exposed host ports?

No. Containers on the same Docker network should use the container's internal port and service name. Host ports are primarily for external access from outside Docker.

What network does Docker Compose create by default?

Docker Compose automatically creates a bridge network named {project_name}_default for the application, allowing all services in the same Compose file to communicate with each other.

Notes

• The example in this walkthrough uses a three-container setup with Nginx, Node.js, and MySQL — but the same localhost mistake and fix apply to any container stack: Python + Redis, Go + PostgreSQL, PHP + MariaDB.
• Docker Compose automatically names its bridge network {project_name}_default. You can define custom named networks in your Compose file for more control over which services can reach each other.
• For Kubernetes, the equivalent concept is a Service — pods use the Service name as the DNS hostname to reach other pods, the same way containers use service names in Docker Compose.