Common container startup failures in Docker - Commands & Configuration

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 Output

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 Output

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 Output

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 Output

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 Output

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.

Practice

1. What is a common reason a Docker container might fail to start immediately after running docker run?

easy

A. The container tries to use a port already in use on the host

B. The Docker daemon is running

C. The container image is very large

D. The host has enough free disk space

Solution

1. Step 1: Understand port conflicts in Docker

   If a container tries to bind to a port already used by another process on the host, it cannot start because the port is busy.

2. Step 2: Check other options for relevance

   Options B, C, and D do not prevent container startup immediately; only port conflict causes failure here.

3. Final Answer:

   The container tries to use a port already in use on the host -> Option A

4. Quick Check:

   Port conflict = container startup failure [OK]

Hint: Check if the port is free before starting container [OK]

Common Mistakes:

• Assuming large image size stops container start
• Thinking Docker daemon running causes failure
• Ignoring port conflicts

2. Which of the following docker run commands will correctly set an environment variable named APP_ENV to production?

easy

A. docker run --env APP_ENV production myimage

B. docker run -e APP_ENV production myimage

C. docker run -env APP_ENV=production myimage

D. docker run -e APP_ENV=production myimage

Solution

1. Step 1: Recall correct syntax for environment variables

   The correct flag is -e or --env followed by VAR=VALUE without spaces.

2. Step 2: Analyze each option

   docker run -e APP_ENV=production myimage uses correct syntax: -e APP_ENV=production. Options A, C, and D have syntax errors or missing '=' sign.

3. Final Answer:

   docker run -e APP_ENV=production myimage -> Option D

4. Quick Check:

   Use -e VAR=VALUE for env vars [OK]

Hint: Use -e VAR=VALUE with no spaces for env vars [OK]

Common Mistakes:

• Omitting '=' between variable and value
• Using incorrect flag like -env
• Adding spaces between variable and value

3. Given this command:

docker run -p 8080:80 nginx

What will happen if port 8080 on the host is already used by another service?

medium

A. Docker will automatically choose a different host port

B. The container will fail to start with a port binding error

C. The container will start normally and ignore the port conflict

D. The container will start but the service inside will not work

Solution

1. Step 1: Understand port binding behavior

   If the host port (8080) is already in use, Docker cannot bind the container port to it, causing failure.

2. Step 2: Evaluate other options

   Docker does not auto-select ports unless specified with -P. The container won't start ignoring conflicts or silently fail.

3. Final Answer:

   The container will fail to start with a port binding error -> Option B

4. Quick Check:

   Port in use causes start failure [OK]

Hint: Check host ports before binding with -p [OK]

Common Mistakes:

• Assuming Docker auto-changes ports
• Thinking container starts ignoring conflicts
• Believing service inside fails but container runs

4. You run a container with docker run -v /host/data:/app/data myimage but the container fails to start. What is the most likely cause?

medium

A. The image name is incorrect

B. The container does not have enough CPU resources

C. The host directory /host/data does not exist or has wrong permissions

D. The Docker daemon is not running

Solution

1. Step 1: Understand volume mount requirements

   Docker requires the host directory to exist and be accessible for volume mounts; otherwise, container startup fails.

2. Step 2: Check other options

   Incorrect image name causes image pull errors, not volume mount failure. CPU or daemon issues cause different errors.

3. Final Answer:

   The host directory /host/data does not exist or has wrong permissions -> Option C

4. Quick Check:

   Volume mount fails if host path missing [OK]

Hint: Verify host path exists and permissions before mounting [OK]

Common Mistakes:

• Ignoring host directory existence
• Confusing image name errors with volume errors
• Assuming CPU limits cause mount failures

5. You have a container that fails immediately after starting. You run docker logs container_id and see an error about a missing environment variable DB_HOST. How should you fix this?

hard

A. Add -e DB_HOST=value to the docker run command

B. Increase the container's CPU and memory limits

C. Change the container image to a different one

D. Restart the container without changes

Solution

1. Step 1: Interpret the error message from logs

   The logs indicate the container expects an environment variable DB_HOST which is missing, causing failure.

2. Step 2: Provide the missing environment variable

   Use -e DB_HOST=value in the docker run command to supply the required variable.

3. Step 3: Understand why other options fail

   Restarting without changes won't fix missing vars. Changing image or resources doesn't address environment variables.

4. Final Answer:

   Add -e DB_HOST=value to the docker run command -> Option A

5. Quick Check:

   Missing env var fixed by -e flag [OK]

Hint: Use docker logs to find missing env vars, then add -e [OK]

Common Mistakes:

• Restarting without fixing environment variables
• Changing image unnecessarily
• Increasing resources instead of fixing config