How to Fix Docker Container Not Starting: Common Issues and Solutions

There's a special kind of frustration that comes from running docker run and watching your container immediately exit. No error on screen, no obvious clue, just... nothing. I've been there more times than I care to admit, and after years of debugging these issues across dozens of projects, I can tell you that the problem almost always falls into one of about ten categories.

Let me walk you through each one.

Check the Container Logs First

Before anything else — and I mean before you start Googling or asking ChatGPT — read the logs:

docker logs <container_name_or_id>

If the container exited so fast you don't even know its ID:

docker ps -a

This shows stopped containers along with their exit codes. Pay attention to that exit code — it's a real clue. 0 means the process completed normally (probably a misconfigured entrypoint). 1 is a general application error. 137 means the kernel killed it (usually OOM). 139 is a segfault.

I've solved probably 60% of container issues just by actually reading the logs. It sounds obvious, but you'd be amazed how many people skip this step.

Incorrect or Missing Entrypoint and CMD

If the binary your container is supposed to run doesn't exist inside the image, Docker exits immediately with something like exec: "myapp": executable file not found in $PATH.

How to fix it:

• Shell into the image to see what's actually in there:

docker run --rm -it <image_name> /bin/sh

• Check your Dockerfile. Make sure CMD or ENTRYPOINT points to the right path. A really common mistake is building on one base image but referencing a binary path from a different one.
• If you're overriding the command at runtime, remember that docker run <image> <command> replaces CMD, not ENTRYPOINT.

Port Conflicts

When your container tries to bind to a host port that's already taken, Docker refuses to start with Bind for 0.0.0.0:8080 failed: port is already allocated.

How to fix it:

• Find out what's hogging the port:

lsof -i :8080

• Either kill the conflicting process or map to a different host port:

docker run -p 8081:8080 <image_name>

I hit this constantly when I've forgotten I left another container or a local dev server running.

Insufficient Memory or Resource Limits

Containers that get killed immediately after starting are often hitting memory limits. If you've set --memory and the app exceeds it, the OOM killer steps in. Exit code 137.

How to fix it:

• Check the memory limit:

docker inspect <container_id> | grep -i memory

• Bump it up:

docker run --memory=512m <image_name>

• On Docker Desktop (Mac/Windows), check that the Docker VM itself has enough memory. Settings → Resources.
• Look for memory leaks or excessive startup memory consumption in your app.

Volume Mount Issues

Volume mount problems are sneaky. The container might fail because the target path conflicts with something expected inside the container, the host directory doesn't exist, or there are permission mismatches.

How to fix it:

• Make sure the host path exists before mounting. Docker creates it automatically on Linux, but the empty directory might not be what your app expects.
• Check file permissions — the user inside the container (often non-root) needs read access:

docker run -v /host/path:/container/path:ro <image_name>

• On Mac and Windows, verify the host directory is shared with Docker in Docker Desktop settings.
• Debug named volumes with docker volume ls and docker volume inspect.

Image Doesn't Exist or Failed to Pull

Can't start what you don't have. This happens with wrong image tags, unreachable registries, or expired auth.

How to fix it:

• Pull manually to see the actual error:

docker pull <image_name>:<tag>

• Double-check the image name and tag. Typos in tags are embarrassingly common.
• Re-authenticate if using a private registry:

docker login <registry_url>

File Permission and User Issues

Many modern images run as non-root for security. If the app tries to write to a directory the container user doesn't own, it crashes on startup.

How to fix it:

• Check which user the container runs as:

docker inspect --format='{{.Config.User}}' <image_name>

• Fix ownership in your Dockerfile:

RUN chown -R appuser:appuser /app/data
USER appuser

• Or match the user ID to the host:

docker run --user 1000:1000 <image_name>

Network Configuration Problems

If your container depends on another service (like a database) and that service isn't reachable, the app crashes at startup trying to connect.

How to fix it:

• In Docker Compose, depends_on controls startup order, but it only waits for the container to start — not for the service inside to be ready. Use health checks:

services:
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
  web:
    image: myapp
    depends_on:
      db:
        condition: service_healthy

• Make sure containers are on the same Docker network:

docker network inspect <network_name>

• Use container names as hostnames — but only on user-defined networks. The default bridge network doesn't support DNS resolution between containers, which has tripped me up more than once.

Corrupted Image or Layer

Occasionally a pulled image has corrupted layers, usually from disk space issues or interrupted downloads.

How to fix it:

docker rmi <image_name>
docker pull <image_name>

If disk space is the root cause, clean up first:

docker system prune -a

Be careful with this — it removes ALL unused images, not just dangling ones.

Docker Daemon Issues

Sometimes it's not your container at all — the Docker daemon itself is having a bad day.

How to fix it:

systemctl status docker
sudo systemctl restart docker

On Docker Desktop, try restarting the whole app. Check daemon logs with journalctl -u docker.service on Linux.

Debugging Containers That Exit Immediately

When a container exits instantly and the logs aren't helpful, you need to get creative:

• Override the entrypoint to keep it alive:

docker run --rm -it --entrypoint /bin/sh <image_name>

This drops you into a shell so you can poke around and run commands manually to see what fails.

• Use docker events in another terminal to watch container lifecycle events in real time.
• Run docker inspect to look for misconfigurations in env vars, mounts, and network settings.

Preventing Future Issues

A few habits that save headaches:

• Use health checks in Dockerfiles and Compose files. They catch problems early.
• Pin image tags instead of using latest. Prevents surprise breakage when someone pushes a new version.
• Test images locally before deploying. Run the exact same docker run command you'll use in production.
• Keep Docker updated. A lot of obscure bugs get fixed in engine updates.

Frequently Asked Questions

Why does my container keep restarting?

If you've set --restart=always, Docker keeps restarting a failing container. Check docker logs to find out why it's failing, fix the root cause, then stop the loop with docker update --restart=no <container_id>.

How do I fix "no space left on device"?

Run docker system df to see disk usage. Clean up with docker system prune. For a nuclear option: docker system prune -a --volumes — but this removes everything unused, including volumes.

What does exit code 137 mean?

SIGKILL — the kernel OOM killer terminated your process. Increase memory allocation or reduce your app's memory usage.

Can I restart a stopped container without losing data?

Yes. docker start <container_id> restarts it with its filesystem intact. This is different from docker run, which creates a brand new container.

Why does my container work locally but not in production?

Usually environment differences: missing env vars, different resource limits, network restrictions, or volume paths that don't exist. Use docker inspect to compare configs between environments.

How do I keep a container alive for debugging even if the main process fails?

Override the entrypoint: docker run -it --entrypoint /bin/sh <image> or use tail -f /dev/null as the command to keep it running.

Sources

• Docker Documentation — Troubleshoot and diagnose — Official guide for diagnosing Docker daemon and container issues
• Docker Documentation — docker logs — Reference for viewing container log output
• Docker Documentation — docker inspect — Reference for inspecting container configuration and state
• Dockerfile Reference — Official Dockerfile syntax and best practices