When checking with docker ps, the container status shows Up (Running),
but the service is not accessible from outside (browser, curl) in some cases.

This issue is not about whether the container process is “alive,”
but in most cases is caused by network listening configuration or port mapping settings.

---

Symptoms (The Phantom Service) #

docker ps 

CONTAINER ID   IMAGE     STATUS         PORTS
abcd1234       my-app    Up 10 minutes  0.0.0.0:8080->8080/tcp

Observed State #

• The container is running normally (Up)
• The port appears to be bound correctly

Problem #

When accessing with curl localhost:8080 or a browser:

• Connection refused
• Infinite loading

---

Cause 1: Localhost (127.0.0.1) Binding (Most Common) #

This case accounts for 80–90% of occurrences.

If the application inside the container is listening only on 127.0.0.1,
it is impossible to access it from outside the container (host).
localhost inside a container refers only to the container itself.

How to Check (Inside the Container) #

docker exec -it <container_name> ss -nltp
# or netstat -nltp

LISTEN 0 128 127.0.0.1:8080   <-- confirmed issue (external access impossible)
LISTEN 0 128 0.0.0.0:8080     <-- normal (external access possible)

Note #

With lightweight images such as Alpine or Distroless,
even ss, netstat, or curl may not be available.
In that case, check the application startup logs or
the binding address directly in configuration files such as
application.yml, nginx.conf, etc.

Resolution #

Change the application listening address.

• Before: 127.0.0.1, localhost
• After: 0.0.0.0 (or ::)

---

Cause 2: Port Mismatch #

The port exposed by Docker (-p) does not match the actual port used by the application.

Common Mistake #

docker run -p 8080:8080 my-app

Docker forwards traffic to port 8080 inside the container.
But what if the application is actually listening on port 3000?

Check and Fix #

docker exec -it <container> ss -nltp

LISTEN 0 128 0.0.0.0:3000

# Restart with corrected port mapping
docker run -p 8080:3000 my-app

---

Cause 3: Works Internally but Not Externally #

If the service is accessible from inside the container
but not from the host or external clients, it is a network issue.

Internal Test #

docker exec -it <container> curl localhost:8080

• Success → the application is healthy; network/firewall issue
• Failure → the application itself is unhealthy or hung

Check Points #

• Host firewall (ufw, firewalld)
• Cloud security groups (AWS SG, etc.)
• Whether the service is bound only to a specific private IP

---

Cause 4: Docker Network Configuration Issues #

When using a custom network (user-defined bridge),
external access may be intentionally restricted by design.

Check #

docker inspect <container> | grep -i network

• Verify bridge vs user-defined network
• Confirm whether the container is intended to be externally exposed

---

Log Patterns That Must Be Checked #

docker logs <container>

Common decisive logs:

• Listening on 127.0.0.1
  → Cause 1 confirmed
• Bind failed: Address already in use
  → Port conflict; application did not start
• No service startup logs at all
  → Initialization hang or crash

Tip #

To identify these situations quickly,
it is recommended to configure HEALTHCHECK in the Dockerfile or docker-compose.
When the service is unreachable, the status will be shown as Up (unhealthy),
making the issue much easier to detect.

---

Key Summary #

• Running only indicates that the process is alive; it does not guarantee service availability
• Check in this order:
  • Listening address (127.0.0.1 vs 0.0.0.0)
  • Port mapping vs actual application port
• With lightweight images, logs and configuration files are more important than commands

Following this order,
most cases of “Docker is running but not accessible” are resolved within 10 minutes.

🛠 마지막 수정일: 2025.12.23