Skip to main content

Troubleshooting — The Kitchen Problem Desk

Everyone eventually sees a confusing Docker error. This is the Problem Desk: what the message means, why it happened, and how to get out. Each problem follows the same Problem → Cause → Fix rhythm you know.

1 · "Cannot connect to the Docker daemon"​

Problem

Every Docker command fails with this error.

Cause: The Docker Engine (daemon) isn't running. Docker Desktop is closed, or the service hasn't started.

Fix:

Start Docker service (Linux)
sudo systemctl start docker
Or start Docker Desktop (Mac/Windows)
# Open Docker Desktop from your applications
Verify it's running
docker info
Remember

Docker commands talk to the Docker daemon. If the daemon is off, nothing works. Always check docker info first.

2 · "Port is already allocated"​

Problem

docker run fails with "port is already allocated" or "address already in use."

Cause: Another container (or another program) is already using that port on your computer.

Fix:

Find what's using the port
lsof -i :8080
Or check which Docker container is using it
docker ps --filter "publish=8080"
Option A — stop the other container
docker stop <container-name>
Option B — use a different port
docker run -d -p 9090:80 nginx
Remember

Port mapping is HOST:CONTAINER. If port 8080 on your host is taken, map to a different host port like 9090.

3 · "No space left on device"​

Problem

Docker commands fail, or builds stop mid-way with "no space left on device."

Cause: Docker images, containers, and volumes accumulate over time and fill your disk.

Fix:

Check Docker disk usage
docker system df
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          15        3         4.2GB     3.1GB (73%)
Containers      8         2         120MB     95MB (79%)
Local Volumes   12        4         2.1GB     1.5GB (71%)
Build Cache     20        0         800MB     800MB
Reclaim everything unused
docker system prune -a --volumes
Common mistake

docker system prune -a --volumes removes all unused images, containers, and volumes. Only use it when you're sure you don't need the old ones.

4 · "COPY failed: file not found"​

Problem

docker build fails with "COPY failed: file not found" or "no such file or directory."

Cause: The file you're trying to COPY doesn't exist in the build context, or the path is wrong.

Fix:

Check what's in the build context
ls -la
Make sure you're in the right directory
pwd
Check if .dockerignore excludes it
cat .dockerignore
Remember

The . in docker build -t myapp . defines the build context. Docker can only access files inside that directory. Files outside it (or excluded by .dockerignore) can't be copied.

5 · "Container keeps restarting"​

Problem

docker ps shows the container status as "Restarting" over and over.

Cause: The command in CMD or ENTRYPOINT is crashing immediately. Maybe a missing file, wrong path, or dependency error.

Fix:

See why it's crashing
docker logs <container-name>
Run the container interactively to debug
docker run -it --entrypoint sh <image-name>
Check the Dockerfile CMD
docker inspect <container-name> --format='{{.Config.Cmd}}'
Remember

A restarting container is usually a crash loop. docker logs tells you what's failing. Fix the command, rebuild, and try again.

6 · "permission denied while connecting to the Docker daemon socket"​

Problem

Docker commands fail with "permission denied" on Linux.

Cause: Your user isn't in the docker group. Only root can talk to the Docker daemon by default.

Fix:

Add your user to the docker group
sudo usermod -aG docker $USER
Log out and back in, then verify
docker run hello-world
Remember

On Linux, Docker requires either sudo or membership in the docker group. The group change takes effect after you log out and back in.

7 · "image not found" or "manifest unknown"​

Problem

docker pull or docker run fails with "image not found" or "manifest unknown."

Cause: The image name is wrong, or the tag doesn't exist. Docker Hub is case-sensitive.

Fix:

Check the exact image name and tag
docker search nginx | head -5
Try with the full path
docker pull docker.io/library/nginx:latest
If it's a private registry, make sure you're logged in
docker login
Remember

Docker Hub image names are case-sensitive. nginx ≠ Nginx. Always use lowercase, and check the tag exists.

8 · "network not found" during docker-compose​

Problem

docker compose up fails with "network not found" or "no such network."

Cause: The network was removed while containers still reference it, or a previous docker compose down removed it.

Fix:

Recreate the network and start fresh
docker compose down
docker compose up -d
Or manually create the network
docker network create campus-net
docker compose up -d
Remember

docker compose down removes networks and containers. docker compose up -d recreates them. When in doubt, down then up.