Lesson 9

Docker debugging and troubleshooting

This page focuses on what to do when a container does not run correctly, when the browser cannot reach the app, or when services fail to talk to each other.

First habit

Do not guess first. Check container status, logs, ports, and service names before changing things.

Main tools

docker ps, docker logs, docker exec, and docker inspect solve many beginner issues.

Common causes

Most Docker problems come from wrong ports, wrong env vars, wrong file copies, wrong host names, or missing rebuilds.

Most useful commands

docker ps
docker ps -a
docker logs <container_id>
docker exec -it <container_id> sh
docker inspect <container_id>

Best beginner debugging flow

Step 1
Run docker ps -a to check whether the container is actually running or already exited.

Step 2
Run docker logs to read the startup error.

Step 3
Check port mapping and app port.

Step 4
Go inside the container if needed and inspect files or environment variables.

When the app is not opening

Is the container running?

Is the port mapping correct?

Is the app listening on the same internal port?

Are you opening the correct browser URL?

When app cannot reach the database

Are both containers running?

Are they on the same network?

Is the host name the service name like `db`?

Avoid using `localhost` for another container

Common environment variable issue

process.env.DB_HOST

environment:
  DATABASE_HOST: db

This fails because the app expects DB_HOST, but Compose sends DATABASE_HOST. The names must match exactly.

Check variables inside a container

docker exec -it <container_id> sh
env

This helps confirm whether the expected values were really passed into the running container.

When files are missing

docker exec -it <container_id> sh
ls /app

If the expected files are not present, check your COPY commands and build context in the Dockerfile.

When changes are not showing

docker compose up --build

If you changed code or the Dockerfile, you may still be running an old image. Rebuild before testing again.

Compose debugging commands

docker compose ps
docker compose logs
docker compose logs app
docker compose up --build
docker compose down

Volume debugging

Check whether the volume is mounted to the right path.
Check whether the app writes to that exact mounted folder.
Wrong path means the volume will not help.

Network debugging

Check service names and network membership.
Use service names like db instead of changing IPs.
Inside a container, localhost means that same container.

What you learned in Lesson 9

Debugging starts with facts
Check status and logs before changing Docker files or application code.

Most issues repeat
Wrong ports, wrong env vars, wrong service names, and missing rebuilds are very common.

Container inspection is practical
Going inside the container helps verify files, paths, and runtime values.

Compose has its own useful checks
Service logs and Compose status make multi-container debugging easier.

Next step: after debugging basics, you are ready for more advanced topics like health checks, production patterns, and deployment workflows.