Most Docker problems fall into a few groups. Once you know which group you're in, the fix is usually short. This lesson gives you a checklist, the common causes, and the command that reveals each one.
Learning Objectives
- Find the cause of a container that won't start, using status, logs, and inspect.
- Fix port conflicts, lost data, and networking problems.
- Check disk usage before it becomes a crisis.
Step by Step: Debug a Failing Container
- Run docker ps -a. Find the container and read its STATUS column. An Exited status with a code other than 0 means the program failed.
- Run docker logs <name>. The last few lines usually name the problem, such as a missing file or a wrong password.
- Run docker inspect <name> and check the Config section for the command, environment variables, and mounts it actually received.
- Fix the cause in your command, Dockerfile, or environment file, then remove the old container and run it again.
Check the Status
docker ps -a
Read the Logs
docker logs <name>
Inspect the Details
docker inspect <name>
Fix, Then Start Again
docker start <name>
Common Problems and Fixes
| Problem | Usual cause | What to do |
|---|---|---|
| Container exits right away | The main program crashed or finished | Read docker logs. Make sure the process in CMD runs in the foreground. |
| Port is already in use | Another program or container uses the same host port | Pick a different host port, such as -p 8081:80, or stop the other program. |
| Data disappears after removing a container | Data was written inside the container, not a volume | Mount a named volume with -v at the path where the app writes data. |
| Container can't reach another container by name | Both containers are on the default bridge network | Create a user-defined network and attach both containers to it. |
| Disk is full | Old images, stopped containers, and volumes use space | Check docker system df, then clean up carefully as shown in the commands lesson. |
| Changes to the code don't show up | The image was built before the change, or an old container is still running | Rebuild with docker build, remove the old container, and run the new image. |
Useful Debug Commands
| Command | What it tells you |
|---|---|
| docker ps -a | Every container and its status, including stopped ones |
| docker logs <name> | What the program printed |
| docker inspect <name> | Full configuration: command, environment, mounts, and network |
| docker stats | Live CPU and memory use of running containers |
| docker system df | How much disk space images, containers, and volumes use |
| docker network ls | Networks that exist on this machine |
| docker exec -it <name> sh | A shell inside a running container, to check files and connections |
Common Mistakes
Starting with a random fix instead of the logs
Changing the Dockerfile or the port before reading the logs often hides the real cause. Read the logs first.
Forgetting to remove the old container
docker run with the same name fails if an old container exists. Remove it, or use a new name.
Assuming a rebuild is not needed
A running container keeps the image it was started from. After a code change, build a new image and run it.
Interview Questions
How do you troubleshoot a container that keeps exiting?
Check its status with docker ps -a, read the logs with docker logs, and inspect its configuration with docker inspect. Then fix the cause and start a new container.
What does docker stats show?
Live CPU and memory use of running containers, which helps spot a container that is using too many resources.
Summary
Start with the status, read the logs, inspect the configuration, then fix one thing at a time. Most problems are a port conflict, a missing volume, a network name, or a stale image.