09 - Docker Troubleshooting and Common Issues

Docker Troubleshooting and Common Issues

While using Docker you may run into various problems. This article highlights common Docker issues and fixes to help you work smoothly with Docker.

Container fails to start

When a container won’t start, troubleshoot with these steps:

Check container logs

docker logs <container_id>

Inspect container state

docker inspect <container_id>

Common causes and fixes

Port conflict: If the port is already in use, the container can’t start. Use a different port or stop the process occupying it.

# Check host port usage
netstat -tuln

# Use a different port mapping
docker run -p 8081:80 nginx

Resource limits: The container may fail due to insufficient memory, etc.

# Increase container memory
docker run --memory=1g myapp

Bad command: The container start command may be wrong.

# Start with a custom command
docker run -it --entrypoint /bin/bash myapp

Container exits immediately

If a container stops right after start:

Main process exits: A container’s lifecycle is tied to its main process. If it exits, the container stops.

# Check container exit code
docker inspect <container_id> --format='{{.State.ExitCode}}'

Fixes:

Ensure a foreground process stays running
Use the right CMD or ENTRYPOINT
For services, ensure the service process does not exit

# Example: correct start command for nginx
CMD ["nginx", "-g", "daemon off;"]

Container cannot access the internet

Possible causes:

DNS config issues

# Check DNS config
docker exec <container_id> cat /etc/resolv.conf

# Run container with custom DNS
docker run --dns 8.8.8.8 myapp

Network mode issues

# Use host network mode
docker run --network host myapp

Firewall rules: Check if host firewall blocks container traffic.

Image build fails

Common causes:

Dockerfile syntax errors

# Check Dockerfile syntax
docker build --no-cache -t myapp .

Large build context: Too many unnecessary files slow or break builds.

# Use .dockerignore to exclude files
echo "node_modules\n.git" > .dockerignore

Network problems: Downloading dependencies may fail due to network issues.

# Use host network during build
docker build --network=host -t myapp .

Image pull fails

Common causes when pulling from Docker Hub or other registries:

Network connectivity

# Check network
ping registry-1.docker.io

Registry auth issues

# Log in to Docker Hub or private registry
docker login

Image missing or wrong tag

# Check if image exists
docker search nginx

Use registry mirrors (for users in China)

# Edit /etc/docker/daemon.json
{
  "registry-mirrors": ["https://registry.cn-hangzhou.aliyuncs.com"]
}

# Restart Docker
sudo systemctl restart docker

Storage issues

Disk space exhaustion

Docker can consume lots of disk space. Solutions:

Prune stopped containers

# Remove all stopped containers
docker container prune

Prune unused images

# Remove all unused images
docker image prune -a

Prune unused volumes

# Remove all unused volumes
docker volume prune

Prune everything unused

# Clean all unused Docker objects
docker system prune -a

Data persistence issues

Causes and fixes for lost container data:

No volume or bind mount: Data disappears when the container is removed.

# Persist data with a volume
docker run -v my-vol:/app/data myapp

Volume permission issues

# Check volume permissions
docker run --rm -v my-vol:/data alpine ls -la /data

# Fix permissions
docker run --rm -v my-vol:/data alpine chown -R 1000:1000 /data

Network issues

Container-to-container communication problems

Check network config

# List networks
docker network ls

# Inspect container network settings
docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' <container_id>

Ensure containers are on the same network

# Create a custom network
docker network create my-network

# Connect containers to the same network
docker network connect my-network container1
docker network connect my-network container2

Use Docker Compose: Compose creates a shared network automatically.

Port mapping issues

Check port mappings

# View container port mappings
docker port <container_id>

Ensure host port is free

# Check host port usage
netstat -tuln | grep 8080

Check the app listens inside the container

# Inspect inside container
docker exec -it <container_id> netstat -tuln

Docker daemon issues

Docker service won’t start

Check daemon status

# Docker service status
sudo systemctl status docker

View Docker logs

# Docker logs
sudo journalctl -u docker

Common fixes

# Restart Docker
sudo systemctl restart docker

# Reset Docker config
sudo systemctl stop docker
sudo rm -rf /var/lib/docker
sudo systemctl start docker

Docker daemon uses too many resources

Limit container resource usage

# Limit CPU and memory
docker run --cpus=0.5 --memory=512m myapp

Tune daemon config

// /etc/docker/daemon.json
{
  "storage-driver": "overlay2",
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

Docker Compose issues

Service dependency issues

Use depends_on to control start order

services:
  web:
    depends_on:
      - db
  db:
    image: postgres

Use health checks to ensure readiness

services:
  db:
    image: postgres
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
  web:
    depends_on:
      db:
        condition: service_healthy

Network and volume issues

Inspect networks and volumes

# View networks and volumes created by Compose
docker network ls
docker volume ls

Use external networks or volumes

networks:
  external-network:
    external: true

volumes:
  external-volume:
    external: true

Performance issues

Poor container performance

Monitor container resource usage

# Container resource usage
docker stats

Check for resource contention

# Limit container resources
docker run --cpus=2 --memory=2g myapp

Use appropriate storage driver

// /etc/docker/daemon.json
{
  "storage-driver": "overlay2"
}

Images and containers consume too much space

Optimize Dockerfiles

Use multi-stage builds
Combine RUN instructions
Clean caches and temporary files

Regularly prune unused Docker objects

# Cron job for periodic cleanup
0 0 * * * docker system prune -f

Common debugging tools and commands

Debug inside a container

# Enter a running container
docker exec -it <container_id> /bin/bash

# View container logs
docker logs -f <container_id>

# View container processes
docker top <container_id>

Network debugging

# Install network tools
docker exec -it <container_id> sh -c "apt-get update && apt-get install -y iputils-ping net-tools curl"

# Test network connectivity
docker exec -it <container_id> ping google.com

System-level debugging

# Docker system info
docker info

# Docker events
docker events

# Docker disk usage
docker system df

Summary

This article summarized common Docker issues and troubleshooting methods, including container startup failures, networking, and storage problems. With these techniques you can use Docker more efficiently and resolve issues faster in real projects.

Remember: the Docker docs and community forums are valuable resources. For complex issues, don’t hesitate to ask the community.

Previous10 - Docker Practical ExamplesLearn real-world Docker scenarios and best practices