Docker Container Won't Start? Here's How to Actually Fix It

Look, most container startup failures are caused by stupidly simple problems that make you feel like an idiot once you figure them out. I've spent entire afternoons debugging containers that wouldn't start because of a missing space in a command. Last month I burned 3 hours on a recent Docker version because some security change broke containers that used to work fine - kept getting "operation not permitted" errors for no obvious reason.

The Top 3 Things That Will Ruin Your Day

Your Command Is Wrong - This is usually the first place to look. Did you typo the command? Is the executable actually in the container? I once spent 4 hours debugging a container that failed because someone wrote httpd-foregroun instead of httpd-foreground. Four. Hours. The logs just said "exec: httpd-foregroun: executable file not found in $PATH" and I kept looking for missing dependencies like a moron.

Docker's official troubleshooting guide actually covers this, but it's buried in enterprise nonsense.

Check this shit first:

## Override the entrypoint and poke around
docker run -it --entrypoint /bin/bash your-broken-image
## Then see if your command actually exists
which your-command
ls -la /path/to/your/script

Memory/Resource Issues - Docker containers are surprisingly good at running out of memory and not telling you why. The container just dies with exit code 137 and you're left wondering what the hell happened. Recent Docker Desktop versions finally show OOMKill status in the GUI, but it took them years to add something this basic.

Pro tip: Check if Docker murdered your container:

docker inspect dead-container --format '{{.State.OOMKilled}}'

This Stack Overflow thread about OOMKilled containers explains the whole mess. Exit code 137 is Docker's shitty way of saying "I killed your app because memory."

If it returns true, you're out of memory. If false, something else killed it. Usually AWS because you forgot to pay your bill, or Kubernetes decided your container was "unhealthy" for taking 3 seconds to respond during startup.

Permission Problems - Oh, the classic "permission denied" that makes no sense because you're running as root in the container anyway. Some recent Docker version introduced new security bullshit that breaks containers that used to work fine. This happens when:

• Your entrypoint script isn't executable (chmod +x fixes this)
• Volume mounts have the wrong ownership
• SELinux is being a pain in the ass (disable it and try again) - this particularly fucks over RHEL 9 users

This Stack Overflow thread about permission denied issues has thousands of answers because this breaks constantly.

When Things Go Wrong (Spoiler: It's Always During Demo)

Here's when your containers will decide to break, in order of how much it will ruin your day:

Image Pull Fails - Your container can't even start because Docker can't download the image. Docker Hub goes down pretty regularly (I think it was down for hours sometime in early 2024 but can't remember exactly when). Usually because:

• You typo'd the image name (docker.io/my-ap instead of docker.io/my-app)
• Your internet connection sucks
• The registry is down (looking at you, Docker Hub)
• Authentication failed because you forgot to docker login
• Rate limiting - Docker Hub now limits pulls to 200 per 6 hours for free accounts

Creation Phase - Docker downloaded the image but can't create the container. I hit this constantly when switching between projects. Common culprits:

• Port 8080 is already taken (check with netstat -tulpn | grep :8080) - some abandoned container is hogging it
• Your volumes point to directories that don't exist (/home/user/data vs /Users/user/data on Mac)
• You've run out of disk space (again) - Docker images are huge and /var/lib/docker fills up fast

Startup Phase - The container starts but immediately crashes. This is where 90% of your debugging time goes. The command is wrong, dependencies are missing, or permissions are fucked.

Runtime Crashes - Container starts fine but dies randomly. Could be memory leaks, external dependencies going away, or your code just sucks.

Why Docker Debugging Is Different (And Annoying)

Docker containers are like black boxes that explode and disappear, taking all the evidence with them. Traditional debugging doesn't work because:

Everything Is Ephemeral - Container dies, logs disappear, and you're left with nothing. Always mount a volume for logs or you'll hate yourself later.

Isolation Works Too Well - You can't just SSH into a container to poke around. Well, you can docker exec, but the container has to be running first.

Layer Upon Layer Of Complexity - Your app runs in Docker, on Kubernetes, on AWS - when it breaks, good fucking luck figuring out which layer is the problem. Each layer has its own logs, configs, and ways to fail.

Tools That Actually Help

Skip the fancy enterprise tools and use these:

Docker logs - First thing to check, though they're often useless:

docker logs -f broken-container
## Add timestamps to see when things break
docker logs -f --timestamps broken-container

Docker inspect - Shows you everything about the container:

docker inspect broken-container | grep -i error

Override the entrypoint - When all else fails:

docker run -it --entrypoint /bin/bash broken-image

The Docker Desktop extensions in Desktop 4.33+ are actually pretty useful if you're into clicking buttons instead of typing commands. The logs explorer saves me from scrolling through thousands of log lines.

For more debugging techniques that actually work, check out this comprehensive Docker troubleshooting guide from DigitalOcean. They know what they're talking about, unlike most Docker tutorials.

Once you've identified that your container is actually failing (and not just being slow), the next step is decoding Docker's cryptic exit codes. These numbers are Docker's attempt at telling you what went wrong, though they're about as clear as mud.

Exit codes are Docker's cryptic way of telling you something went wrong. Here's what the most common ones actually mean and how to fix them without losing your mind.

Exit Code 137: Docker Murdered Your Container

Exit code 137 means your container got SIGKILL'd - basically the operating system said "fuck this" and killed it. Most of the time it's because you ran out of memory. Recent Docker versions are stricter about memory limits, so this happens way more often now.

This complete guide to exit codes explains all the cryptic numbers Docker throws at you.

First, check if it was OOMKilled:

docker inspect dead-container --format '{{.State.OOMKilled}}'

If it returns true, you're out of memory. The container tried to use more RAM than you gave it, so Linux killed it. Solution: give it more memory or fix your memory leak. Pro tip: Newer Docker Desktop versions actually show OOMKill status in the GUI now instead of making you run inspect commands.

If it returns false, something else killed it:

• You hit Ctrl+C
• Your orchestrator (Kubernetes) killed it
• System ran out of resources
• Your monitoring tool decided to restart it

Check system memory:

free -h
dmesg | grep -i "killed process"  # Look for OOM killer messages

Fix it:

## Give it more memory (if you ran out)
docker run -m 2g your-image

## Or find out what's eating memory
docker stats your-container

Exit Code 125: You Fucked Up the Docker Command

Exit code 125 means Docker couldn't even create the container because your command was wrong. Usually it's a typo in your docker run command or you don't have permission to use Docker.

The Docker daemon troubleshooting docs cover this, but they assume you already know what you're doing.

Common fuckups:

• Typo in the image name or flags (postgres:14.1 vs postgres:14.1.0)
• You're not in the docker group and forgot to use sudo
• Docker daemon isn't running (Docker Desktop takes forever to start on Windows)
• You used flags that don't exist (they change between Docker versions)
• Docker is still starting up - wait 30 seconds and try again

Check the basics:

## Is Docker actually running?
docker version

## Are you allowed to use Docker?
groups $USER | grep docker

## Try the simplest possible container
docker run --rm hello-world

If hello-world fails, Docker is broken. If it works, your command is the problem.

Exit Code 126/127: Your Command Doesn't Exist

Exit code 126: File exists but isn't executable (usually missing chmod +x)
Exit code 127: Command not found (typo or not installed in the image)

Debug it:

## Override entrypoint and poke around
docker run --rm -it --entrypoint /bin/bash your-broken-image

## Inside the container:
which python3        # Is the command in PATH?
ls -la /app/start.sh # Does your script exist? Is it executable?
echo $PATH           # Check your PATH variable

Common fixes:

• Add RUN chmod +x /app/start.sh to your Dockerfile
• Install the missing package (RUN apt-get install python3)
• Fix the typo in your command name
• Use the full path: /usr/bin/python3 instead of just python3

I once spent 3 hours debugging this because I had python in my Dockerfile but the Ubuntu base image only had python3. The error message was completely useless - just "exec: python: executable file not found in $PATH". No shit, Docker. Took me way longer than I want to admit to figure out such a stupid mistake.

This Stack Overflow thread about executable file not found shows how common this problem is.

Network Issues That Make No Sense

Sometimes containers can't talk to each other or the outside world. This is usually because Docker's networking is confusing and the documentation assumes you understand it (you don't).

Docker's networking docs are technically correct but about as helpful as a broken compass when you're debugging at 3am.

Can't reach other containers?

## Check what networks exist
docker network ls

## See which containers are on which networks
docker network inspect bridge

## Test connectivity between containers
docker exec -it container1 ping container2

Pro tip: Don't use the default bridge network. Create your own:

docker network create my-network
docker run --network my-network --name db postgres
docker run --network my-network --name app my-app

Now app can reach db by name. Magic.

The Nuclear Option: Start Over

Sometimes the fastest solution is to blow everything up and start fresh:

When Docker is completely fucked:

## Delete all containers (running and stopped)
docker rm -f $(docker ps -aq)

## Delete all images 
docker rmi -f $(docker images -q)

## Delete all networks
docker network prune -f

## Delete all volumes (careful with this one)
docker volume prune -f

When you need to debug a dead container:

## Copy files out of a stopped container
docker cp dead-container:/var/log/app.log ./

## Look at what changed in the container
docker diff dead-container

## See exactly how it died
docker inspect dead-container --format '{{.State}}'

Debugging with persistence:

## Mount a volume so logs survive container death
docker run -v $(pwd)/logs:/var/log/myapp my-broken-app

This way when your container crashes at 3am, the logs are still there in the morning.

Testing Your Fixes (Because They Probably Don't Work)

Don't trust that your fix works. Test it properly:

## Test startup 5 times to make sure it's not just luck
for i in {1..5}; do
  docker run --rm my-app echo "Test $i: OK" || echo "Test $i: FAILED"
done

## Stress test with multiple containers
for i in {1..10}; do
  docker run -d --name stress_$i my-app &
done

If it works 5 times in a row, it's probably fixed. If it fails once, you're not done yet.

The goal is to spend less time debugging and more time building actual features. Docker debugging follows predictable patterns - once you know the exit codes and have a systematic approach, most problems become trivial to solve.

The key insight: Docker failures usually happen at predictable stages (image pull, container creation, process startup, runtime), and each stage has common failure modes. Learn to identify which stage failed, match it to the right exit code, and apply the corresponding fix.

This systematic approach will get you there faster than randomly googling error messages at 3am.

Now that you understand what the exit codes mean, let's get into the actual solutions that fix these problems. Forget the theoretical bullshit - these are the battle-tested approaches I use when debugging breaks at 3am and I need containers running again before the morning standup.

Here are the solutions I wish someone had told me before I spent weeks debugging stupid Docker problems when some Docker update changed how volume mounts work and broke half our CI pipeline. These aren't "best practices" - they're the ugly hacks that actually get containers running in production.

Fix Exit Code 137: When Docker Murders Your Container

Most of the time exit code 137 means you ran out of memory. Recent Docker versions are stricter about memory limits, so this breaks constantly now. My Node.js containers used to work fine, then Docker updated and suddenly they're all OOMKilling.

Quick fix - give it more memory:

docker run -m 2g your-image

Better fix - actually monitor memory usage:

## Run your app and watch memory usage
docker stats your-container

## Set appropriate limits (give yourself headroom)
docker run -m 1g --memory-swap 2g your-image

Don't disable OOM killer (--oom-kill-disable) unless you enjoy having your system crash when containers eat all your RAM. I learned this the expensive way on a production server - some Java thing went crazy and ate all the memory, crashed the whole server. All I remember is the panic and explaining to my boss why the entire site was down.

Fix Permission Problems (The Classic Fuckup)

Exit code 126 means your script exists but can't execute. Usually because you forgot to make it executable.

Always do this in your Dockerfile:

COPY start.sh /app/
RUN chmod +x /app/start.sh
CMD ["/app/start.sh"]

Exit code 127 means the command doesn't exist. Check if it's actually installed:

## Debug interactively
docker run -it --entrypoint /bin/bash your-image

## Inside the container:
which python3    # Is python3 installed?
echo $PATH       # Is the binary in PATH?
ls -la /usr/bin/ # What binaries are available?

Architecture mismatch - if you built the image on Mac M1 but running on Intel:

## Check what architecture your image is
docker inspect your-image --format '{{.Architecture}}'

## Build for the right platform
docker build --platform linux/amd64 .

I've wasted entire days on architecture mismatches. Docker finally warns you about platform mismatches now, but older versions just failed silently. This Stack Overflow thread about M1 platform issues has hundreds of developers with the same problem - M1 Macs trying to run x86 images.

Environment Variables and Configuration Hell

Your app probably expects certain environment variables to exist, and Docker gives you no fucking clue when they're missing.

Debug missing env vars:

## See what environment variables are actually set
docker run --rm your-image env

## Or run your container with debugging
docker run -it your-image /bin/bash -c 'echo $DATABASE_URL'

Volume mount problems - these will make you want to quit programming. Docker keeps changing how paths work and breaking tutorials:

## Make sure the host directory exists first
mkdir -p /host/data

## Check permissions (Docker might run as different user)
ls -la /host/data

## Test the mount works
docker run --rm -v /host/data:/container/data alpine ls -la /container/data

Pro tip: If your app needs specific file ownership, set it in the Dockerfile:

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

Don't try to figure out Docker's user mapping. It's a nightmare that gets worse with each version. The official Docker documentation about user namespaces is technically correct but practically insane. Docker keeps changing user namespace behavior and breaking containers that used to work fine.

Port and Network Bullshit

Port already in use - this happens constantly:

## See what's using your port
netstat -tulpn | grep :8080

## Kill the process (nuclear option)
sudo lsof -ti:8080 | xargs kill -9

## Or just use a different port
docker run -p 8081:8080 your-image

Container can't reach the internet:

## Test basic connectivity
docker run --rm alpine ping -c 3 google.com

## Test specific services
docker run --rm alpine nc -zv your-database.com 5432

If ping fails, your Docker networking is fucked. Restart Docker daemon and try again. On Windows with WSL2, this fails half the time because Microsoft and Docker can't figure out how networking should work.

When All Else Fails: Nuclear Options

Clear the build cache - sometimes Docker caches broken shit and you get inconsistent builds. Docker's BuildKit cache is aggressive and will cache failed intermediate layers:

This Docker blog post about debugging containers has some decent advice, though it's full of corporate bullshit:

## Clear everything (be careful)
docker builder prune -a

## Rebuild from scratch
docker build --no-cache --progress=plain .

Inspect what went wrong:

## See image layers
docker history your-broken-image

## Debug specific build stages
docker run -it --entrypoint /bin/bash intermediate-layer-id

Extract files from dead containers:

docker cp dead-container:/app/logs ./debug-logs/

This Stack Overflow post about inspecting failed builds shows more techniques for extracting data from broken containers. The intermediate container trick saved my ass when debugging a multi-stage build that failed at some ridiculous step late in the process - I think it was 15 out of 20 or something equally soul-crushing.

Prevention (So You Don't Hate Your Life)

Add health checks so you know when shit breaks:

HEALTHCHECK --interval=30s --timeout=10s --start-period=60s \
  CMD curl -f /health || exit 1

Monitor resource usage in development:

docker stats --no-stream

Set your production limits based on these numbers plus 50% overhead. Don't be cheap with memory.

The reality: Most Docker problems are stupid configuration errors that take 5 minutes to fix once you know what to look for. The hard part is knowing what to look for, which takes experience you get from fucking things up over and over again.

I've been there - staring at "exec: /app/start.sh: no such file or directory" at 3am on a Sunday, questioning whether I should have just become a bartender instead. But once you build up your debugging toolkit and learn to recognize the patterns, Docker becomes much less mysterious. The container either has enough resources, correct permissions, and working commands - or it doesn't. Everything else is just noise and Docker being dramatic.

This shit will save you from 3am debugging hell where you question all your life choices.