Introduction

Sometimes containers fail to start because of simple mistakes like missing files, wrong commands, or port conflicts. Understanding these common errors helps fix problems quickly and keeps your apps running smoothly.

When your container stops immediately after starting and you need to find out why

When your app inside the container is not reachable even though the container is running

When you want to check if the container has permission to access needed files or folders

When you suspect the container command or entrypoint is incorrect

When ports used by the container clash with other services on your machine

Commands

This command runs an Nginx container named 'my-nginx' and maps port 8080 on your computer to port 80 inside the container. It helps check if the container starts and serves web pages.

Terminal

docker run --name my-nginx -p 8080:80 nginx

Expected OutputExpected

Unable to find image 'nginx:latest' locally latest: Pulling from library/nginx Digest: sha256:... Status: Downloaded newer image for nginx:latest f3c1a2b4d5e6c7f8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o3p4q5r6s7t8u9v0w1x2

→

--name - Assign a name to the container for easier management

→

-p - Map host port to container port for network access

This command lists all running containers so you can verify if 'my-nginx' is running after the start command.

Terminal

docker ps

Expected OutputExpected

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES f3c1a2b4d5e6 nginx "/docker-entrypoint.…" 10 seconds ago Up 9 seconds 0.0.0.0:8080->80/tcp my-nginx

This command shows the logs from the 'my-nginx' container. Logs help find errors if the container failed to start or is not working properly.

Terminal

docker logs my-nginx

Expected OutputExpected

2024/06/01 12:00:00 [notice] 1#1: using the "epoll" event method 2024/06/01 12:00:00 [notice] 1#1: nginx/1.23.3 2024/06/01 12:00:00 [notice] 1#1: built by gcc 11.2.0 2024/06/01 12:00:00 [notice] 1#1: start worker processes 2024/06/01 12:00:00 [notice] 1#1: start worker process 31

This command runs a container that immediately exits because the command '/bin/false' returns failure. It shows how a wrong command causes startup failure.

Terminal

docker run --name bad-container -p 8080:80 busybox /bin/false

Expected OutputExpected

No output (command runs silently)

→

--name - Name the container for easy reference

→

-p - Map ports even if container fails to start

This command lists all containers including stopped ones. It helps find containers that failed to start and exited immediately.

Terminal

docker ps -a

Expected OutputExpected

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES b7d9c8a7f6e5 busybox "/bin/false" 5 seconds ago Exited (1) 4 seconds ago bad-container f3c1a2b4d5e6 nginx "/docker-entrypoint.…" 2 minutes ago Up 2 minutes 0.0.0.0:8080->80/tcp my-nginx

→

-a - Show all containers, including stopped ones

Key Concept

If a container fails to start, check its logs and status to find errors like wrong commands, missing files, or port conflicts.

Common Mistakes

Running a container with a command that exits immediately like '/bin/false'

The container stops right away because the command finishes with failure, so the app never runs

Use a valid long-running command or default entrypoint that keeps the container alive

Mapping a port already used by another service on the host

Docker cannot bind the port, so the container fails to start or the port is inaccessible

Choose a free port on the host when using the -p flag

Not checking container logs after a failure

Without logs, you miss error messages that explain why the container stopped

Always run 'docker logs <container-name>' to see error details

Summary

Use 'docker run' with proper commands and port mappings to start containers.

Check running containers with 'docker ps' and all containers with 'docker ps -a'.

Use 'docker logs' to find errors when containers fail to start.