Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
178 lines (120 loc) · 3.3 KB

TROUBLESHOOTING.md

File metadata and controls

178 lines (120 loc) · 3.3 KB

Docker Troubleshooting Guide

Common Issues and Solutions

Issue: "Cannot connect to Docker daemon"

Solution:

# Check if Docker is running
docker ps

# Start Docker Desktop (Windows/Mac)
# Or start Docker service (Linux)
sudo systemctl start docker

Issue: "Port already in use"

Solution:

# Find what's using the port
# Windows
netstat -ano | findstr :8080

# Linux/Mac
lsof -i :8080

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

Issue: "Permission denied" (Linux)

Solution:

# Add user to docker group
sudo usermod -aG docker $USER

# Log out and log back in, or:
newgrp docker

Issue: "Out of disk space"

Solution:

# Clean up unused resources
docker system prune -a

# Remove unused volumes
docker volume prune

# Remove unused images
docker image prune -a

Issue: Container exits immediately

Solution:

# Check logs
docker logs container-name

# Run interactively to see errors
docker run -it image-name bash

# Check if CMD/ENTRYPOINT is correct
docker inspect image-name

Issue: Can't access container from host

Solution:

  • Check port mapping: docker ps shows port mappings
  • Verify firewall settings
  • Check if container is listening on 0.0.0.0 not 127.0.0.1
  • Verify network configuration

Issue: Changes not reflecting in container

Solution:

  • Rebuild image after code changes
  • Use volumes for development: -v $(pwd):/app
  • Restart container after changes

Issue: Environment variables not updating (e.g., NODE_ENV still showing old value)

Problem: You changed ENV variables in Dockerfile but the container still shows old values.

Solution:

# Stop and remove the old container
docker stop container-name
docker rm container-name

# Rebuild the image (use --no-cache to ensure changes are applied)
docker build --no-cache -t image-name:tag .

# Run a new container with the rebuilt image
docker run -d -p 3000:3000 --name container-name image-name:tag

# Verify the environment variable
docker exec container-name printenv NODE_ENV

Note: Changes to ENV in Dockerfile only take effect in newly built images. Simply restarting a container won't update environment variables set in the Dockerfile - you must rebuild the image and create a new container.

Alternative: Override at runtime (this doesn't require rebuild):

docker run -d -e NODE_ENV=production -p 3000:3000 --name container-name image-name:tag

Issue: "No space left on device"

Solution:

# Check disk usage
docker system df

# Clean up
docker system prune -a --volumes

Debugging Commands

# Inspect container
docker inspect container-name

# View container logs
docker logs container-name

# Execute command in container
docker exec -it container-name sh

# View container processes
docker top container-name

# View network details
docker network inspect network-name

# View volume details
docker volume inspect volume-name

Getting Help

  1. Check Docker documentation: https://docs.docker.com
  2. Search Stack Overflow
  3. Check GitHub issues
  4. Docker community forums

Useful Commands

# System information
docker info
docker version

# Resource usage
docker stats

# System events
docker events

# Clean everything
docker system prune -a --volumes