Docker is awesome. It simplifies development, deployment, and scaling. But if you've used Docker long enough, you've definitely seen your fair share of annoying cryptic errors. Some make you scratch your head, others make you want to pull your hair out. Don’t worry—you’re not alone!
This guide covers common Docker errors, what they actually mean, and how to fix them. Whether you're a beginner or just trying to save some Googling time, this one's for you.
1. Docker: "Cannot connect to the Docker daemon"
Error:
Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
What It Means:
Docker can't communicate with its background service (the daemon). This often happens when Docker isn't running, or you're not allowed to access it.
Fix:
sudo systemctl start docker
sudo systemctl restart docker
- Also, ensure your user is in the
docker group:
sudo usermod -aG docker $USER
newgrp docker
Then try again.
2. Image Pull Fails: "manifest for xyz not found"
Error:
Error response from daemon: manifest for my-image:latest not found
What It Means:
Docker tried to pull an image tag that doesn't exist (usually latest), or the image name is incorrect.
Fix:
- Double-check the image name and tag.
- Use Docker Hub or the image registry to confirm available tags.
- Explicitly pull a valid version:
docker pull node:20-alpine
⛔ 3. "Port is already allocated"
Error:
Error starting userland proxy: Bind for 0.0.0.0:80 failed: port is already allocated
What It Means:
You're trying to expose a container on a port your system is already using—like port 80 for a web server.
Fix:
- Find out what's using that port:
sudo lsof -i :80
- Either stop the conflicting process or use a different host port in your
docker run command:
docker run -p 8080:80 my-container
️ 4. "No space left on device"
Error:
write /var/lib/docker/tmp/...: no space left on device
What It Means:
Your disk is full, especially where Docker stores images and volumes.
Fix:
- Clean up unused Docker stuff:
docker system prune -a
docker system df
- You can also remove dangling volumes:
docker volume prune
Be careful—pruning deletes unused data.
5. Dockerfile Errors (e.g., COPY failed: no such file)
Error:
COPY failed: stat /app/file.txt: no such file or directory
What It Means:
Docker can't find the file you're trying to copy because it doesn’t exist in your build context (usually the same folder as your Dockerfile).
Fix:
- Make sure you're in the right directory when building.
- Ensure the file path is correct and relative to the Dockerfile.
COPY ./file.txt /app/file.txt
6. Permission Denied Errors Inside Containers
Error:
Permission denied: /app/output.log
What It Means:
The process inside your container doesn't have permission to access a file or directory.
Fix:
- Set correct ownership or permissions:
RUN chown -R appuser:appuser /app
- Or run the container as root temporarily (not recommended for production):
docker run --user root ...
7. Containers Restarting Repeatedly
Symptoms:
docker ps -a
# shows container with status "Restarting"
What It Means:
Your container crashes right after starting. Docker tries to restart it automatically due to your restart policy.
Fix:
docker logs <container_id>
- Fix the underlying error—usually a missing config, bad environment variable, or crash in your app.
- You can also stop it from restarting so you can debug:
docker update --restart=no <container_id>
Bonus: Tips for Easier Debugging
- Use
docker logs <container> to see output from a container.
- Use
docker exec -it <container> bash to get inside a running container.
- Use
docker-compose for more readable setups and shared environments.
- Make use of
.dockerignore to avoid bloating your build context.
Always clean up your unused containers, images, and volumes regularly. A bloated Docker environment can slow everything down!
Final Thoughts
Errors in Docker can seem intimidating at first, but the more you work with it, the easier it becomes to understand what's going on. Use the logs, pay attention to the error messages, and don’t be afraid to prune and rebuild.
Your future self (and your CI/CD pipeline) will thank you.
