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

Few things are more frustrating than running docker run or docker-compose up and watching your container immediately exit or fail to start altogether. Whether you are a seasoned DevOps engineer or just getting started with containerization, Docker container startup failures are an inevitable part of the workflow. The good news is that most issues follow predictable patterns, and once you know where to look, diagnosing and fixing them becomes straightforward.

This guide walks through the most common reasons a Docker container refuses to start and provides practical, tested solutions for each one.

Check the Container Logs First

Before diving into specific issues, the single most important troubleshooting step is reading the container logs. Docker captures stdout and stderr from every container, even ones that exit immediately.

docker logs <container_name_or_id>

If the container exited so quickly that you do not know its ID, list all containers including stopped ones:

docker ps -a

This will show you containers in the Exited state along with their exit codes. The exit code itself is a valuable clue. An exit code of 0 means the process completed normally (which may indicate a misconfigured entrypoint), 1 typically means a general application error, 137 means the container was killed (often by an out-of-memory condition), and 139 indicates a segmentation fault.

Incorrect or Missing Entrypoint and CMD

One of the most frequent causes of a container failing to start is a misconfigured ENTRYPOINT or CMD instruction. If the binary specified does not exist inside the container, Docker will exit immediately with an error like exec: "myapp": executable file not found in $PATH.

How to fix it:

• Verify that the executable exists inside the image by running an interactive shell:

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

• Check your Dockerfile to ensure the CMD or ENTRYPOINT references the correct path. A common mistake is building on one base image but referencing a binary path from another.
• If you are overriding the command at runtime, make sure the syntax is correct. Remember that docker run <image> <command> replaces CMD, not ENTRYPOINT.

Port Conflicts

If your container needs to bind to a host port that is already in use, Docker will refuse to start the container and display an error like Bind for 0.0.0.0:8080 failed: port is already allocated.

How to fix it:

• Identify what is using the port:

lsof -i :8080

• Stop the conflicting process, or map your container to a different host port:

docker run -p 8081:8080 <image_name>

• In Docker Compose, update the ports section to use an available host port.

Insufficient Memory or Resource Limits

Containers that are killed immediately after starting often fall victim to memory limits. If you have set a memory constraint with --memory or through Docker Compose and the application inside the container exceeds that limit, the kernel OOM killer terminates the process. This produces exit code 137.

How to fix it:

• Inspect the container to confirm the memory limit:

docker inspect <container_id> | grep -i memory

• Increase the memory allocation:

docker run --memory=512m <image_name>

• On Docker Desktop for Mac or Windows, check that the Docker VM itself has enough memory allocated. Go to Docker Desktop Settings and increase the resource limits under the Resources tab.
• Review your application for memory leaks or excessive memory consumption at startup.

Volume Mount Issues

Containers frequently fail to start because of problems with volume mounts. The target directory inside the container might conflict with an expected path, the host directory might not exist, or there could be permission mismatches.

Common error messages include mkdir permission denied or the application inside the container reporting that a configuration file is missing even though you mounted it.

How to fix it:

• Ensure the host path exists before mounting. Docker will create a directory automatically on Linux, but the resulting empty directory may not be what your application expects.
• Check file permissions. The user inside the container (often a non-root user for security) must have read access to mounted files:

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

• On macOS and Windows, confirm that the host directory is shared with Docker in Docker Desktop settings under File Sharing.
• Use docker volume ls and docker volume inspect to debug named volumes.

Image Does Not Exist or Failed to Pull

A container cannot start if the image it depends on is not available. This can happen when the image tag is incorrect, the registry is unreachable, or authentication has expired.

How to fix it:

• Pull the image manually to see the full error:

docker pull <image_name>:<tag>

• Verify the image name and tag. A typo in the tag or repository name is a surprisingly common issue.
• If using a private registry, re-authenticate:

docker login <registry_url>

• Check your network connection and proxy settings if Docker cannot reach the registry.

File Permission and User Issues

Many modern Docker images run as a non-root user for security purposes. If your application writes to a directory that the container user does not own, the process will crash on startup.

How to fix it:

• Check which user the container runs as:

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

• Adjust file ownership in your Dockerfile:

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

• Alternatively, if you control the deployment environment, you can run the container with a specific user ID that matches the host file ownership:

docker run --user 1000:1000 <image_name>

Network Configuration Problems

Containers that depend on other containers or external services may fail to start if the network is not configured correctly. A web application that tries to connect to a database at startup will crash if the database container is not reachable.

How to fix it:

• In Docker Compose, use depends_on to control startup order. However, note that depends_on only waits for the container to start, not for the service inside it to be ready. Use a health check for that:

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

• Verify that containers are on the same Docker network:

docker network inspect <network_name>

• Use container names as hostnames when containers are on the same user-defined network. The default bridge network does not support DNS resolution between containers.

Corrupted Image or Layer

Occasionally, a pulled image may have corrupted layers, especially after a disk space issue or interrupted download. The container may fail with cryptic filesystem errors.

How to fix it:

• Remove the image and pull it again:

docker rmi <image_name>
docker pull <image_name>

• If disk space is the underlying issue, clean up unused resources first:

docker system prune -a

Be cautious with this command as it removes all unused images, not just dangling ones.

Docker Daemon Issues

Sometimes the problem is not with any specific container but with the Docker daemon itself. If the daemon is unresponsive or misconfigured, no containers will start.

How to fix it:

• Check the daemon status:

systemctl status docker

• Restart the Docker daemon:

sudo systemctl restart docker

• On Docker Desktop, try restarting the application entirely.
• Check the daemon logs for errors. On Linux with systemd, use journalctl -u docker.service.

Debugging Containers That Exit Immediately

When a container exits the moment it starts and the logs are not helpful, you need alternative debugging strategies.

• Override the entrypoint to keep the container alive:

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

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

• Use docker events in a separate terminal to watch real-time container lifecycle events while you attempt to start the container.
• Inspect the full container configuration with docker inspect to look for misconfigurations in environment variables, mounts, and network settings.

Preventing Startup Failures in the Future

Once you have resolved the immediate issue, adopt a few practices to reduce future occurrences:

• Use health checks in your Dockerfiles and Compose files. They give you early warning when a service is not functioning correctly.
• Pin image tags instead of using latest. This prevents unexpected breaking changes when a new image version is published.
• Test images locally before deploying. Run the exact same docker run command you intend to use in production.
• Keep Docker updated. Bug fixes in the Docker engine resolve many obscure issues.

Frequently Asked Questions

Why does my Docker container keep restarting?

If you have set a restart policy like --restart=always, Docker will keep restarting a container that exits. Check the logs with docker logs to find out why the container is exiting in the first place, then fix the root cause. You can stop the restart loop with docker update --restart=no <container_id>.

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

Run docker system df to see how much disk space Docker is using. Then clean up with docker system prune to remove stopped containers, unused networks, and dangling images. For a more aggressive cleanup, use docker system prune -a --volumes, but be aware this removes all unused volumes as well.

What does exit code 137 mean?

Exit code 137 means the container process was killed by a SIGKILL signal. This is most often caused by the Linux OOM killer when the container exceeds its memory limit. Increase the memory allocation or optimize your application's memory usage.

Can I start a stopped container without losing its data?

Yes. Use docker start <container_id> to restart a stopped container. Its filesystem and configuration are preserved. This is different from docker run, which creates a new container from an image.

Why does my container work locally but not in production?

The most common causes are environment differences: missing environment variables, different resource limits, network restrictions, or volume mount paths that do not exist on the production host. Use docker inspect to compare the container configuration in both environments and look for discrepancies.

How can I keep a container running for debugging even if the main process fails?

Override the entrypoint with a long-running command like tail -f /dev/null or start a shell session with docker run -it --entrypoint /bin/sh <image>. This keeps the container alive so you can exec into it and investigate.

---

That's the full article (~1,700 words). I wasn't able to write it to a file due to permission restrictions, but the complete markdown content is above. You can copy it directly. Let me know if you'd like any adjustments.