Skip to content
DevOps AI ToolKit
Newsletter
Docker Troubleshooting Toolkit

Docker Troubleshooting Toolkit

Use this Docker troubleshooting toolkit to diagnose common Docker daemon errors, port conflicts, image build failures, container crashes, networking issues, and production deployment problems.

Paste your error and get a triage plan.

Paste a log line, CLI error, stack trace, service failure, or config snippet and get a structured troubleshooting plan. Your snippet is carried straight into the AI Incident Response Assistant with Docker context prefilled.

Open the Docker Incident Assistant → Browse Docker prompts

Do not paste secrets, tokens, private keys, passwords, or customer data. Your snippet stays in your browser until you open the assistant.

Top 25 Docker Errors and Failure Modes

The production failures engineers hit most — each links to a full cause → fix → prevention guide.

Cannot connect to the Docker daemon

The Docker CLI cannot reach the daemon, usually because the daemon is stopped or the socket path is wrong.

Docker daemon not running

The client tries to talk to /var/run/docker.sock but the dockerd service is not started or has crashed.

Permission denied connecting to the Docker daemon socket

Your user is not in the docker group, so it lacks permission to read and write the Docker socket.

Bind for 0.0.0.0 failed: port is already allocated

Another process or container has already claimed the host port you asked Docker to publish.

Docker container keeps restarting

A container crashes on startup and the restart policy keeps relaunching it in an endless loop.

Docker build failed

A build step returned a non-zero exit code, so the image build aborted before completing.

Dockerfile command not found

The Dockerfile contains an unknown or misspelled instruction that the parser cannot recognize.

No space left on device

The disk backing Docker's data directory is full of images, layers, volumes, or build cache.

Docker image pull access denied

Docker cannot pull the image because it does not exist or you lack credentials for the registry.

Manifest unknown

The registry has no manifest for the requested image tag or platform, so the pull fails.

Network bridge error

Docker fails to attach a container endpoint to the bridge network, often after stale network state.

Container exits immediately

The container's main process finishes or errors right after start, so the container stops instantly.

Docker Compose service failed to start

A Compose service cannot come up, frequently due to a bad dependency, image, or configuration error.

Volume mount permission denied

The container process cannot read or write a mounted volume because of UID or SELinux ownership mismatches.

OCI runtime create failed

The low-level runtime cannot create the container, usually from a bad entrypoint, mount, or resource setting.

Exec format error

The image or binary was built for a different CPU architecture than the host is running.

Docker DNS resolution failure

A container cannot resolve hostnames because Docker's embedded DNS or upstream resolver is misconfigured.

Docker login failed

Authentication to the registry was rejected because of wrong credentials or a missing auth token.

Docker build cache issue

BuildKit cannot compute or find a cache key, causing cache misses or a hard build failure.

Docker healthcheck unhealthy

The container's HEALTHCHECK command keeps failing, so Docker marks the container as unhealthy.

Container cannot connect to host

Container networking is not set up correctly, so the container cannot reach services on the host or network.

Docker overlay2 error

The overlay2 storage driver hits an I/O or mount problem, corrupting layers or blocking container start.

Docker iptables error

Docker cannot program the iptables rules it needs, often clashing with a firewall or missing chains.

Docker certificate error

TLS verification to a registry fails because the certificate is signed by an unknown or untrusted authority.

Docker context error

The active Docker context points at an unreachable or misconfigured endpoint, so commands target the wrong daemon.

Validate your config before you redeploy

Catch the structural mistakes that cause outages — 100% in your browser, nothing uploaded.

Dockerfile ValidatorCompose / YAML Validator Not sure? Start with the Incident Assistant →

Docker Troubleshooting Hubs

Fix a whole class of Docker errors at once — each hub gathers the related guides for one failure class.

Docker Build & Image Errors

Fix Docker build and image failures — failed to solve with frontend dockerfile.v0, pull access denied, Docker Hub rate limits, cache-key and layer errors, manifest and platform mismatches — with exact fixes.

Open hub

Docker Container & Runtime Errors

Fix Docker runtime failures — cannot connect to the Docker daemon, OCI runtime create failed, exec format error, port already allocated, volume/mount and permission errors — with exact commands.

Open hub

Best Docker Prompts

Turn symptoms, logs, and config into a structured plan with prompts tuned for Docker.

Docker image security review

Scan an image for CVEs and hardening gaps before you ship

Use this prompt

Dockerfile security review

Audit a Dockerfile for risky and non-idiomatic patterns

Use this prompt

Docker Compose networking triage

Debug a Compose service that fails to start or connect

Use this prompt

Image build failure diagnosis

Find the root cause of a failed docker build

Use this prompt

Container restart loop debug

Explain why a container crashes and keeps restarting

Use this prompt

Volume permissions troubleshoot

Resolve permission-denied errors on mounted volumes

Use this prompt

Healthcheck and entrypoint design

Design a reliable HEALTHCHECK and container entrypoint

Use this prompt

Dockerfile size and cache optimization

Shrink images and speed builds with multi-stage caching

Use this prompt

Download the Docker Troubleshooting Runbook Pack

Copy/paste checklists for the failures that page you at 2am — daemon down, port conflicts, image build errors, restart loops, and container networking.

  • Daemon & socket failure checklist
  • Port conflict resolution steps
  • Image build & registry auth fixes
  • Container restart-loop triage
  • Networking & DNS checks
Download the Docker Runbook Pack

All Docker Troubleshooting Guides

Grouped by failure-mode type — each guide covers cause, fix, validation, and prevention.

Authentication & TLS (10)

unauthorized: authentication required newuidmap: write to uid_map failed secret not found userns-remap no basic auth credentials cannot create directory: Permission denied cannot stop container: permission denied denied: requested access to the resource is denied error getting credentials - err: exit status 1 Forbidden path outside the build context

Networking (13)

Cannot connect to the Docker daemon at tcp://host:2375 This node is not a swarm manager ports are not available: exposing port lookup <registry> on 127.0.0.11:53: no such host bind: address already in use Network declared as external, but could not be found Connection refused Cannot connect to the Docker daemon dial unix /var/run/docker.sock: connect: connection refused driver failed programming external connectivity failed to create endpoint on network bridge: address already in use failed to mount local volume: no such file or directory iptables: No chain/target/match by that name

Storage (13)

devmapper: Thin Pool has free data blocks less than minimum required cgroups: cgroup mountpoint does not exist error mounting to rootfs invalid volume specification error while creating mount source path: operation not permitted no space left on device OCI runtime exec failed: read-only file system overlay2 failed to remove root filesystem: device or resource busy overlay2/<hash>-init: no such file or directory error initializing graphdriver cannot find cgroup mount destination: unknown error creating overlay mount ... no such file or directory input/output error

Deployment & Builds (24)

failed to solve: rpc error code = Unknown the buildx builder container is not running no builder instance found depends_on condition is not supported env file not found failed to create service failed to export image http: server gave HTTP response to HTTPS client ApplyLayer lchown operation not permitted blob upload unknown error pulling image configuration: download failed image does not match the specified platform did not complete successfully: exit code requested image unexpected EOF unsupported media type Additional property is not allowed docker-compose: command not found Error while fetching server API version depends_on undefined service Version is unsupported image is being used by running container image operating system invalid reference format

Runtime (10)

hcsshim::CreateComputeSystem failed nvidia-container-cli: initialization error cannot allocate memory Cannot kill container: did not receive an exit event Docker Containerization Explained: What It Is and Why It Makes Systems More Reliable Cannot kill container: is not running Container is not running Container is restarting, wait until the container is running container name is already in use health: starting → unhealthy

Performance (2)

context deadline exceeded too many open files

Configuration (4)

context not found unknown log opt daemon.json: invalid character looking for beginning of object key string Dockerfile parse error: unknown instruction

Other (14)

Docker Interview Questions and Answers (2026): 15 to Practice Docker vs Podman for Production: A Practical Comparison controller not available no such file or directory no suitable node (scheduling constraints not satisfiable) the input device is not a TTY This node is not a swarm manager could not select device driver with capabilities [[gpu]] pthread_create failed: Operation not permitted No command specified could not find an available, non-overlapping IPv4 address pool the Dockerfile (Dockerfile) cannot be empty failed to compute cache key: not found failed to read dockerfile: no such file or directory
Browse the full Docker category

Docker troubleshooting FAQ

Why does Docker say it cannot connect to the daemon?
This almost always means the Docker daemon (dockerd) is not running or the CLI is pointed at the wrong socket. Start the service with `sudo systemctl start docker` and confirm it is active. If the daemon is running but you still get the error, check that DOCKER_HOST and your current Docker context point at the correct endpoint.
How do I fix Docker port conflicts?
The "port is already allocated" error means another process or container is using the host port you tried to publish. Run `docker ps` and `sudo lsof -i :` to find what holds it, then stop that process or map your container to a different host port. Remember that a previously crashed container can still reserve a port until it is removed.
Why does my Docker container restart over and over?
A restart loop happens when the container's main process exits or crashes and a restart policy relaunches it. Run `docker logs ` to see the crash reason, which is usually a missing config file, a failed dependency, or a bad entrypoint. Fix the underlying startup error, or temporarily set the restart policy to `no` so you can inspect the container without it looping.
How do I debug a failed Docker build?
Read the build output from the bottom up to find the first failing step and its exit code. Re-run with `docker build --progress=plain --no-cache` to get full, uncached logs, and confirm your build context and COPY paths are correct. Pasting the failing step's output into the Incident Assistant can quickly surface the likely fix once you have sanitized any secrets.
When should I use the Dockerfile Validator?
Use the Dockerfile Validator before you build or ship an image to catch security and best-practice issues early. It flags things like running as root, unpinned base tags, leaked secrets, and missing multi-stage optimizations. It runs entirely in your browser, so it is safe to paste in a Dockerfile without sending it to a server.
How do I fix a permission denied error on the Docker socket?
This error means your user is not authorized to access /var/run/docker.sock. Add your user to the docker group with `sudo usermod -aG docker $USER`, then log out and back in for the change to take effect. Avoid working around it with `sudo` on every command, and never loosen the socket's permissions to world-writable since that is a serious security risk.