🧩 1.
Image-Related Issues
1. Image Pull Fails (Error: repository not found)
○ Cause: Image name or tag incorrect.
○ Fix: Verify docker pull nginx:latest syntax and image exists on
Docker Hub/private repo.
2. Error: unauthorized: authentication required
○ Cause: Trying to pull from a private registry without login.
○ Fix: Run docker login <registry-url>.
3. Slow image download
○ Cause: Network latency or large image layers.
○ Fix: Use a local mirror or slim image (python:3.12-slim).
4. Build fails with no space left on device
○ Cause: /var/lib/docker is full.
○ Fix: docker system prune -a or expand disk.
5. Build context too large
○ Cause: .dockerignore missing, large files copied.
○ Fix: Add .dockerignore to exclude unnecessary directories.
6. Dockerfile COPY fails (“file not found”)
○ Cause: Wrong path relative to build context.
○ Fix: Ensure file is inside build directory or adjust COPY path.
7. Image build hangs on RUN command
○ Cause: Command waiting for user input (e.g., apt install prompt).
○ Fix: Add -y flag or use noninteractive mode.
8. Image not updating after rebuild
○ Cause: Cache not invalidated.
○ Fix: Use --no-cache flag during build.
9. Multi-stage build failing on final COPY
○ Cause: Wrong stage name or missing artifacts.
○ Fix: Check FROM builder as build name consistency and file existence.
10.“exec format error” on container start
○ Cause: Built image on different architecture (ARM vs x86).
○ Fix: Use --platform flag or rebuild for correct arch.
🧱 2. Container Startup Issues
11.Container exits immediately after start
○ Cause: Main process completes or fails.
○ Fix: Use docker logs <id> and ensure command runs in foreground.
12.Error: OCI runtime create failed
○ Cause: Permissions or incompatible cgroup.
○ Fix: Check Docker version and systemd compatibility.
13.Port already in use (Error: bind: address already in use)
○ Cause: Another service using same host port.
○ Fix: Use different port mapping (-p 8081:80).
14.Error: standard_init_linux.go:xxx: exec user process caused "no
such file or directory"
○ Cause: Wrong line endings (Windows CRLF).
○ Fix: Convert script to LF (dos2unix [Link]).
15.Container cannot find command (executable file not found)
○ Cause: Wrong CMD or missing binary.
○ Fix: Use full path or install dependency in image.
16.Container restarts repeatedly (CrashLoop)
○ Cause: Application crash or bad config.
○ Fix: Use docker logs and docker inspect to diagnose.
17.Environment variables not set properly
○ Cause: Wrong syntax or missing -e flag.
○ Fix: Use docker run -e VAR=value or --env-file.
18.Permission denied when writing to mounted volume
○ Cause: UID mismatch between host and container user.
○ Fix: Adjust ownership or use --user flag.
19.Container stuck in Created state
○ Cause: Missing entrypoint or startup command.
○ Fix: Verify ENTRYPOINT and CMD in Dockerfile.
20.Container timezone mismatch
○ Cause: Container uses UTC by default.
○ Fix: Mount /etc/localtime or use TZ env var.
🌐 3. Networking Issues
21.Container cannot reach internet
○ Cause: DNS or proxy misconfiguration.
○ Fix: Check /etc/[Link], or use --dns flag.
22.Host cannot access container via exposed port
○ Cause: Port not published.
○ Fix: Use -p <host>:<container> or check firewall.
23.Containers cannot reach each other
○ Cause: Not on same Docker network.
○ Fix: Connect to same bridge or overlay network.
24.Custom network not created (network not found)
○ Cause: Missing creation step.
○ Fix: docker network create mynet then run containers.
25.DNS resolution fails inside container
○ Cause: Internal DNS issue.
○ Fix: Restart Docker daemon or use --dns=[Link].
26.Port conflicts in Compose setup
○ Cause: Multiple services exposing same host port.
○ Fix: Change host mappings in [Link].
27.Ping between containers fails
○ Cause: ICMP disabled or using wrong network driver.
○ Fix: Use bridge or overlay, not none or host.
28.Proxy not applied inside container
○ Cause: Proxy env vars not passed.
○ Fix: Use HTTP_PROXY, HTTPS_PROXY, and NO_PROXY.
💾 4. Storage & Volume Issues
29.Data lost after container restart
○ Cause: Data not stored in a volume.
○ Fix: Use -v /data:/app/data or named volume.
30.Volume mount overwrites container directory
○ Cause: Mounting over pre-existing data.
○ Fix: Copy data before mounting or use docker cp.
31.Volume permissions denied
○ Cause: Host directory owned by root.
○ Fix: Adjust permissions or run container as same UID.
32.Bind mount path not found
○ Cause: Host path does not exist.
○ Fix: Create directory before running container.
33.Volume cleanup not freeing space
○ Cause: Dangling volumes.
○ Fix: docker volume prune.
34.Named volume not updating between rebuilds
○ Cause: Volume persists old data.
○ Fix: Remove volume manually before rebuild.
⚙️ 5. Docker Daemon & System Issues
35.Docker daemon not starting (failed to start daemon)
○ Cause: Corrupt state file or missing cgroups.
○ Fix: Remove /var/lib/docker or reinstall Docker.
36.Error: Cannot connect to the Docker daemon
○ Cause: Daemon not running or permission denied.
○ Fix: Start service sudo systemctl start docker.
37.Too many containers slowing host
○ Cause: Resource exhaustion.
○ Fix: docker container prune and limit CPU/memory.
38.High disk usage under /var/lib/docker
○ Cause: Old layers and logs.
○ Fix: docker system prune -a --volumes.
39.BuildKit errors (rpc error: code = Unknown)
○ Cause: Incompatible Docker version or bad cache.
○ Fix: Disable BuildKit: DOCKER_BUILDKIT=0.
40.Docker Compose fails with version mismatch
○ Cause: Outdated Compose binary or YAML version.
○ Fix: Update to latest Compose and correct YAML syntax.
🐳 Docker Troubleshooting Scenarios
(50 Practical Cases)
🧱 1. Container Start & Runtime Problems
1. Container starts and exits right away
○ Cause: Main command finishes instantly.
○ Fix: Use a long-running command (tail -f /dev/null) or run
interactively with -it.
2. Error: “exec user process caused: no such file or directory”
○ Cause: Windows line endings (CRLF) or missing binary.
○ Fix: Convert scripts to LF (dos2unix [Link]), and confirm executable
path.
3. Container stuck in “Created” state
○ Cause: Entrypoint or CMD misconfigured.
○ Fix: Inspect image with docker inspect image to verify startup
command.
4. App in container keeps restarting
○ Cause: Process crash or invalid configuration.
○ Fix: View crash logs using docker logs -f <container> and fix startup
parameters.
5. Permission denied while accessing a file in container
○ Cause: File owned by root or wrong user mapping.
○ Fix: Use --user flag or adjust permissions (chown, chmod) on host.
6. Container cannot execute shell commands (/bin/sh: not found)
○ Cause: Minimal image without shell (e.g., alpine, scratch).
○ Fix: Use apk add bash or rebuild with a shell installed.
7. Container keeps restarting even after fixing config
○ Cause: Old container cached by name.
○ Fix: Remove with docker rm -f <name> and recreate fresh.
8. “Container already exists” when trying to run
○ Cause: Container name conflict.
○ Fix: Use unique name or remove existing one.
9. Container time zone mismatch with host
○ Cause: Default UTC inside container.
○ Fix: Mount /etc/localtime:/etc/localtime:ro or set TZ variable.
10.Error: invalid reference format when running image
○ Cause: Typo or missing tag in image name.
○ Fix: Verify format repository:tag (e.g., nginx:latest).
📦 2. Image Build & Tagging Issues
11.Docker build fails due to missing files in COPY step
○ Cause: Files outside build context or typo in path.
○ Fix: Place all required files in the same directory or adjust COPY path.
12.Image too large
○ Cause: Unnecessary packages or layers.
○ Fix: Use multi-stage builds or base images like alpine.
13.Dockerfile stuck at RUN step
○ Cause: Interactive prompt (e.g., apt-get install waiting for input).
○ Fix: Add -y or use DEBIAN_FRONTEND=noninteractive.
14.Build error: no space left on device
○ Cause: /var/lib/docker full.
○ Fix: Clean with docker system prune -a.
15.Tag missing after successful build
○ Cause: Forgot -t flag.
○ Fix: Run docker build -t myimage:1.0 .
16.Build uses old code changes
○ Cause: Cached layers.
○ Fix: Use --no-cache to force rebuild.
17.Multi-stage build fails copying artifact
○ Cause: Incorrect stage name or missing file.
○ Fix: Match names (FROM builder AS build) and verify file exists.
18.Image fails to run on another host
○ Cause: Architecture mismatch (ARM vs x86).
○ Fix: Build with platform flag: --platform linux/amd64.
19.“Manifest unknown” when pulling image
○ Cause: Nonexistent tag or private registry restriction.
○ Fix: Check available tags or login to registry.
20.Build extremely slow
○ Cause: Large context or slow dependency downloads.
○ Fix: Add .dockerignore and use local mirrors.
🌐 3. Network & Connectivity Issues
21.Container cannot reach external internet
○ Cause: Host firewall or missing NAT.
○ Fix: Restart Docker service or update iptables.
22.Host can’t access app on container port
○ Cause: Port not mapped.
○ Fix: Use -p 8080:80 flag and ensure container listens on [Link].
23.Containers on same network cannot communicate
○ Cause: Not attached to same bridge/overlay network.
○ Fix: Connect both with docker network connect.
24.DNS inside container not resolving
○ Cause: Internal resolver broken or proxy conflict.
○ Fix: Add --dns [Link] or restart daemon.
25.Container tries to reach host using localhost but fails
○ Cause: localhost refers to container itself.
○ Fix: Use [Link] (Windows/macOS) or host IP.
26.Service name resolution fails in Docker Compose
○ Cause: Not on same network or service name typo.
○ Fix: Confirm both services share a Compose network.
27.Port already in use error
○ Cause: Another process occupies host port.
○ Fix: Run sudo lsof -i :8080 and free it or remap port.
28.Container cannot ping another
○ Cause: ICMP disabled or using host network mode.
○ Fix: Use user-defined bridge for inter-container communication.
29.Proxy not working inside container
○ Cause: Proxy env vars not passed.
○ Fix: Set HTTP_PROXY, HTTPS_PROXY, and NO_PROXY.
30.Docker swarm service not reachable
○ Cause: Overlay network misconfigured.
○ Fix: Recreate service network and redeploy stack.
💾 4. Storage & Data Volume Problems
31.Data disappears after container restart
○ Cause: Data written to ephemeral layer.
○ Fix: Use named volumes or bind mounts.
32.Permission denied writing to mounted directory
○ Cause: Host directory owned by root.
○ Fix: Match user IDs or use --user $(id -u).
33.Mounted folder overwrites container data
○ Cause: Empty host directory hiding container files.
○ Fix: Copy default data to host before mounting.
34.Volume not updating between runs
○ Cause: Persistent data from previous runs.
○ Fix: Remove volume using docker volume rm <name>.
35.Volume cleanup doesn’t reclaim space
○ Cause: Unused anonymous volumes.
○ Fix: Run docker volume prune.
36.Bind mount path doesn’t exist
○ Cause: Missing folder on host.
○ Fix: Create path before mounting.
37.Container reads stale data after file edit on host
○ Cause: File caching in overlay filesystem.
○ Fix: Restart container or disable caching option.
38.Database container data loss after rebuild
○ Cause: Volume not defined in compose file.
○ Fix: Add volumes: mapping in [Link].
⚙️ 5. Docker Daemon, Service, and Resource Issues
39.Docker daemon won’t start
○ Cause: Corrupted state or missing cgroup drivers.
○ Fix: Check /var/log/[Link], remove /var/lib/docker, or
reinstall.
40.Cannot connect to Docker daemon (permission denied)
○ Cause: Non-root user not in docker group.
○ Fix: Run sudo usermod -aG docker $USER.
41.Docker consumes too much disk space
○ Cause: Old images, containers, logs.
○ Fix: docker system prune -a --volumes.
42.BuildKit errors (rpc error: code = Unknown)
○ Cause: Docker version incompatibility.
○ Fix: Disable BuildKit with DOCKER_BUILDKIT=0.
43.Slow container startup
○ Cause: Heavy initialization scripts or network waits.
○ Fix: Use healthchecks and optimize entrypoint.
44.High CPU usage by idle containers
○ Cause: Tight loops or healthcheck spam.
○ Fix: Inspect with docker stats and tune app behavior.
45.Container memory limit ignored
○ Cause: cgroup configuration missing on host.
○ Fix: Ensure host kernel supports cgroups v2.
46.Compose fails with version unsupported
○ Cause: YAML version mismatch.
○ Fix: Update Compose binary and YAML schema.
47.Docker pull timing out
○ Cause: DNS or registry latency.
○ Fix: Change mirror or configure registry proxy.
48.Daemon logs flooded with overlay2 warnings
○ Cause: Storage driver instability.
○ Fix: Switch driver (aufs, btrfs, or overlay2).
49.Container logs filling disk quickly
○ Cause: No log rotation configured.
○ Fix: Add log driver options in /etc/docker/[Link].
50.Docker socket permission denied when CI/CD runs builds
○ Cause: Pipeline user lacks /var/run/[Link] access.
○ Fix: Add proper group permissions or use Docker-in-Docker setup.