Docker Troubleshooting

Common Docker Desktop issues and resolution strategies, particularly for AI development environments requiring substantial disk space and container resources.

Disk Space Issues

Symptoms

• Build failures with "No space left on device"
• I/O errors during container operations
• Docker daemon hanging or unresponsive
• Commands timing out without response

Resolution Strategy

1. Check host disk space:

   df -h  # Should have >5GB free for Docker operations
   

2. Analyze Docker space usage:

   docker system df
   # Shows containers, images, volumes, build cache usage
   

3. Clean Docker data (progressive approach):

   # Start with unused containers/networks
   docker system prune -f
   
   # Remove all unused images
   docker system prune -a -f
   
   # Clean build cache
   docker builder prune -a -f
   

4. Factory reset (when Docker is corrupted):

   # Quit Docker Desktop completely
   # macOS: Remove VM data
   rm -rf ~/Library/Containers/com.docker.docker/Data/vms
   
   # Restart Docker Desktop (will recreate VM)
   

VM Corruption Recovery

Complete Reset Process

When Docker Desktop becomes unresponsive after disk issues:

1. Full shutdown:

   killall com.docker.backend
   killall Docker\ Desktop
   

2. Remove all Docker data:

   # macOS locations
   rm -rf ~/Library/Containers/com.docker.docker
   rm -rf ~/.docker
   

3. Restart with factory settings:

   • Launch Docker Desktop
   • Accept new terms/conditions
   • Allow symlink repair when prompted

Symlink Issues

After factory reset, Docker Desktop may show symlink warnings:

• /usr/local/bin/docker-compose pointing to old installation
• Solution: Click "Repair" in Docker Desktop UI
• This updates symlinks to current installation paths

Prevention Strategies

Disk Space Monitoring

• Maintain >10GB free space on host
• Regular cleanup schedules for Docker data
• Monitor build cache growth

Resource Allocation

• Adjust Docker Desktop VM limits appropriately
• Consider external volume mounts for large data

Development Practices

• Use .dockerignore to exclude unnecessary files
• Multi-stage builds to minimize image size
• Regular image cleanup in CI/CD workflows

AI Development Considerations

AI agent platforms like OpenClaw Platform and nemoclaw require:

• Substantial container resources for model inference
• Persistent volumes for agent state
• Network access for API communications
• Security isolation through containerization

Docker stability becomes critical for production AI agent deployment.

See also

• local-llm-deployment - Hardware considerations for AI workloads
• Container Security - Security patterns for AI agent deployment