Skip to main content

Troubleshooting Common Docker Issues

Welcome to Lesson 18! At this stage, you’re building, running, and orchestrating Docker containers with confidence. However, even seasoned professionals encounter issues—containers that won't start, mysterious network problems, or unexpected behavior in production. Understanding how to systematically troubleshoot Docker issues is an essential skill for every developer and DevOps engineer.

In this lesson, we'll cover effective troubleshooting techniques for common Docker problems, provide hands-on examples, and share best practices to help you debug and resolve issues quickly.

Table of Contents​

  1. General Troubleshooting Approach
  2. Container Startup and Crash Issues
  3. Image Build Problems
  4. Networking and Connectivity Issues
  5. Volume and Data Persistence Issues
  6. Resource Constraints and Performance Problems
  7. Common Mistakes and Pitfalls
  8. Summary
  9. Quiz

General Troubleshooting Approach​

Before diving into specific issues, adopt a systematic approach:

  1. Gather Information: Use logs, status commands, and config files.
  2. Isolate the Problem: Is it the image, container, network, or host?
  3. Reproduce the Issue: Does it happen every time? Only on one host?
  4. Check the Docker Documentation: It often lists common errors and fixes.

Useful commands:

docker ps -a                # List all containers, including stopped ones
docker logs <container>     # View a container’s logs
docker inspect <container>  # Detailed info about a container
docker events               # Real-time event stream

Container Startup and Crash Issues​

Problem: Container Exits Immediately​

Symptoms: docker ps -a shows your container exited right after starting.

Common Causes:

  • The main process in the container ends (e.g., CMD or ENTRYPOINT runs and exits).
  • Application crashes due to missing dependencies or misconfiguration.

How to Debug:

  1. Check the logs:

    docker logs <container>

    Look for error messages or stack traces.

  2. Run the container interactively:

    docker run -it --entrypoint /bin/sh <image>

    This lets you access the shell and investigate.

Example:

docker run myapp
# App exits immediately

docker logs <container_id>
# Output: "Error: Configuration file not found."

Solution: Ensure required files are present, and the CMD or ENTRYPOINT is correct.

Problem: Container Fails with "Permission Denied"​

Symptoms: Logs show permission errors.

How to Debug:

  • Inspect file permissions in the image.
  • If using volumes, check host directory permissions.

Example:

docker run -v /host/data:/data myapp
# App fails to write to /data

ls -ld /host/data
# drwxr-xr-x 2 root root 4096 Mar 1 12:00 /host/data

Solution: Set the correct permissions or ownership:

sudo chown 1000:1000 /host/data

(Where 1000 is the UID/GID your container expects.)

Image Build Problems​

Problem: "COPY failed: no source files were specified"​

Symptoms: Build fails when copying files.

How to Debug:

  • Check the Dockerfile path.
  • Make sure files exist in the build context.

Example:

COPY app.py /app/

If app.py does not exist in the context directory, you’ll see this error.

Solution: Ensure all files/directories referenced in COPY or ADD exist in the build context.

Problem: Build Caching Issues​

Symptoms: Old code appears in the image after changes.

How to Debug:

  • Docker caches layers aggressively.
  • If you change files after a cached layer, your changes may not be included.

Solution: Use .dockerignore to exclude unnecessary files. Rebuild without cache:

docker build --no-cache -t myapp:latest .

Networking and Connectivity Issues​

Problem: Container Can't Connect to Other Containers​

Symptoms: Service in one container can’t reach another (e.g., web app can't reach database).

How to Debug:

  1. Check network configuration:

    docker network ls
    docker network inspect <network>

  2. Connect containers to the same network:

    docker run --network mynet ...

  3. Use service names as hostnames in Docker Compose:

    services:
      web:
        ...
      db:
        ...

    In this setup, web can reach db via hostname db.

Pitfall: Using localhost from one container only refers to itself, not to other containers.

Problem: Ports Not Exposed or Mapped​

Symptoms: Can't access your service from the host machine.

How to Debug:

  • Ensure you have EXPOSEd the port in your Dockerfile (for documentation).
  • Ensure you use -p or --publish when running the container: 
    docker run -p 8080:80 myapp
    This maps port 80 in the container to port 8080 on the host.

Volume and Data Persistence Issues​

Problem: Data Not Persisting Between Container Restarts​

Symptoms: Data appears to be lost after restarting or removing a container.

How to Debug:

  • Are you using named volumes or bind mounts?
  • Check your docker run or docker-compose.yml configuration.

Example:

docker run -v mydata:/data myapp

Data in /data will persist as long as the mydata volume exists.

Pitfall: Data stored only in a container’s writable layer is lost when the container is removed.

Problem: File Permission Problems with Volumes​

Symptoms: App can't read/write files from a mounted volume.

How to Debug:

  • Check user IDs inside the container vs. ownership of files on the host.

Solution: Match UID/GID between host and container, or adjust permissions.

Resource Constraints and Performance Problems​

Problem: Out of Memory (OOM) Kills​

Symptoms: Container stops unexpectedly; docker logs may show OOM errors.

How to Debug:

  • Check system logs (dmesg | grep -i oom).
  • Inspect container resource usage.

Solution: Limit memory usage:

docker run -m 512m myapp

Or optimize your application.

Problem: High CPU or Disk Usage​

Symptoms: Host slows down, containers are slow or unresponsive.

How to Debug:

  • Use docker stats to monitor resource usage.
  • Use monitoring tools (as covered in Lesson 15).

Solution: Optimize your application, increase resources, or scale out with more containers.

Common Mistakes and Pitfalls​

  • Forgetting to Map Ports: Not using -p/--publish means your service is inaccessible from outside the container.
  • Using localhost for Inter-Container Communication: Containers need to use service names or container IPs, not localhost.
  • Misunderstanding Volume Persistence: Data in containers (not in volumes) is ephemeral.
  • Missing Files in Build Context: Files outside the build context can't be copied into images.
  • Mismatched User IDs: Causes file permission errors with mounted volumes.
  • Overlapping Container Names: Causes conflicts; use unique names or Docker Compose.

Summary​

Troubleshooting Docker issues requires a structured approach: gather information, isolate the problem, reproduce it, and apply targeted fixes. By mastering common troubleshooting commands and understanding the typical pitfalls, you’ll be able to resolve most Docker-related issues efficiently.

Key takeaways:

  • Use logs and inspect/container status commands.
  • Understand how Docker handles networking, volumes, and process management.
  • Always verify your Dockerfile paths, volume mounts, and port mappings.
  • Resource constraints can silently kill or slow your containers.
  • Practice debugging by running containers interactively.

Quiz​

  1. What command would you use to view the logs of a Docker container named webapp?

    a) docker ps webapp
    b) docker logs webapp
    c) docker inspect logs webapp
    d) docker info webapp

  2. If two containers need to communicate, what is the best way to allow them to see each other?

    a) Use localhost as the hostname
    b) Connect both to the same user-defined bridge network
    c) Use the container's IP address on the host's network
    d) Use the default bridge and localhost

  3. You run docker run -p 8080:80 myapp, but cannot access the service on http://localhost:8080. What is a possible cause?

    a) The app listens on port 80 inside the container
    b) The app is not running
    c) You should have used -v instead of -p
    d) The app is listening on a different port inside the container

  4. What is a common cause of "permission denied" errors when using Docker volumes?

    a) Typo in the Dockerfile
    b) Host directory permissions do not match container user IDs
    c) Using -d for detached mode
    d) Not exposing ports

  5. Which command disables Docker’s build cache for a build?

    a) docker build --no-cache -t myapp .
    b) docker build --clear-cache -t myapp .
    c) docker build --force -t myapp .
    d) docker build --reset -t myapp .

Answers​

  1. b) docker logs webapp
  2. b) Connect both to the same user-defined bridge network
  3. d) The app is listening on a different port inside the container
  4. b) Host directory permissions do not match container user IDs
  5. a) docker build --no-cache -t myapp .

Continue practicing these troubleshooting techniques as you work with Docker in real projects!