Search guides

Fix a Docker container that will not start

We'll check docker logs, docker inspect, and docker run—to isolate exit codes, image issues, and resource limits—or tell you when to escalate.

Troubleshooting · Containers
10–25 min
What you'll need
  • Docker installed and running
  • Container name or ID (or image name to reproduce)
  • Access to run docker logs, docker inspect, docker run
Step 1 of 7

Quick triage — pick your path

Get started

Choose the option that matches what you see. You can jump straight to that section.

Show full guide

Steps

Goal: Find why the container exits, then fix the entrypoint, image, resources, or config.

  • Run docker logs container-name to see the last output.
  • Good: You see an error. Proceed to Check logs and exit code.
  • Bad: Logs empty—run docker inspect for exit code.

Check logs and exit code

Goal: See why the container exited.

  • Run docker logs container-name. Look for permission denied, no such file, address already in use, or app errors.
  • Run docker inspect container-name --format "{{.State.ExitCode}} {{.State.Error}}". Exit 0: clean exit. 137: OOM. 139: segfault. 127: command not found.
  • Good: You have the exit code and logs. Proceed to Reproduce with docker run or Check image and entrypoint.
  • Bad: Container not found—check name or run docker run to create.

Reproduce with docker run

Goal: Run the container and capture errors in real time.

  • Run docker run --rm -it image-name with the same env, volumes, and ports from docker inspect.
  • When it exits immediately, you see the error before the prompt returns.
  • Add --entrypoint /bin/sh to bypass the entrypoint and debug inside the container.
  • Good: You reproduce the failure and see the error.
  • Bad: Container runs—issue may be specific to the original run config.

Check image and entrypoint

Goal: Confirm the entrypoint and exit code make sense.

  • Run docker inspect image-name --format "{{.Config.Entrypoint}} {{.Config.Cmd}}". Wrong or missing entrypoint causes exit 0 or 127.
  • When the image is wrong architecture (amd64 on arm64), you may see “exec format error”. Pull the correct image.
  • Good: Entrypoint and image are valid. Proceed to fix env, volumes, or resources.
  • Bad: Entrypoint wrong or image incompatible—fix Dockerfile or use correct image.

Fix entrypoint or command

Goal: Override the entrypoint or add env when the app needs it.

  • Run docker run --entrypoint /bin/sh image-name -c "your command" to test.
  • Add -e VAR=value for required env vars. Add -v /host/path:/container/path for config files.
  • Update the Dockerfile or run command with the correct entrypoint and env.
  • Good: Container runs and stays up.
  • Bad: Still exits—check resource limits or image.

Fix resource limits or image

Goal: Address OOM or wrong image.

  • When exit code is 137 (OOM), run docker run -m 512m image-name or fix the app.
  • When the image is wrong architecture, pull the correct tag. When the base has a bug, update the Dockerfile.
  • Good: Container starts and runs.
  • Bad: Contact support with logs and inspect output.

When to get help

Contact support or the image maintainer when:

  • Logs and inspect do not reveal the cause.
  • The image is from a vendor and fails consistently.
  • You suspect a Docker or host bug.

Provide container name, image, docker logs output, and docker inspect State and HostConfig. Check Docker and host logs for errors.

Verification

  • docker ps shows the container in Up state (not Exited).
  • docker logs container-name shows the app running (no immediate exit).
  • No restart loop—the container stays up for the expected duration.

Escalation ladder

Work from the device outward. Stop when the problem is fixed.

  1. Check logs Run docker logs to see stdout/stderr before exit.
  2. Check exit code and state Run docker inspect for ExitCode and Error.
  3. Reproduce with docker run Run the image with same flags to capture errors.
  4. Check entrypoint and image Verify entrypoint, cmd, and image architecture.
  5. Fix entrypoint, env, or resources Override entrypoint, add env, increase memory, or fix image.
  6. Contact support Provide logs, inspect output, and image name.

What to capture if you need help

Before calling support or posting for help, have these ready. It speeds everything up.

  • Container name or ID
  • Output of docker logs container-name
  • Output of docker inspect container-name (State, HostConfig)
  • Image name and tag
  • docker run command used (with flags)
  • Steps already tried

Does the container exit immediately or stay in a restart loop?

docker ps -a shows Exited. docker logs shows the last output.

Run `docker ps -a` and `docker logs container-name`. Good: you see Exited and logs—proceed to check exit code. Bad: container not found—check name or ID, or run docker run to create one.

Yes No (running)

You can change your answer later.

Container is running

If the container is running but unreachable, check network, ports, or the app inside. See fix-linux-server-will-not-start-service for service-level issues.

Done

What does docker logs show?

Logs show stdout/stderr from the last run.

Run `docker logs container-name`. Look for "permission denied", "no such file", "address already in use", or app errors. Good: you see an error—proceed to interpret. Bad: logs empty—run docker inspect for exit code.

Yes No / empty

You can change your answer later.

Check docker inspect for exit code

Run `docker inspect container-name --format "{{.State.ExitCode}} {{.State.Error}}"`. Exit 0: app exited cleanly. 137: OOM. 139: segfault. 127: command not found. 126: permission denied. Use that to guide the fix.

Done

Is exit code 0 or non-zero?

0 = clean exit. Non-zero = crash or error.

Run `docker inspect container-name --format "{{.State.ExitCode}}"`. Exit 0: entrypoint or app quit—check entrypoint, cmd, env. Non-zero: crash—check logs for OOM, segfault, missing file.

Yes (0) No (non-zero)

You can change your answer later.

Check entrypoint and cmd

Run `docker inspect image-name --format "{{.Config.Entrypoint}} {{.Config.Cmd}}"`. Wrong or missing entrypoint causes exit 0. Override with `docker run --entrypoint /bin/sh image -c "command"` to test. Fix Dockerfile or run command.

Done

Is it OOM (exit 137) or other crash?

137 = OOM kill. 139 = segfault. 127 = command not found.

137: increase memory with -m or fix app. 139: app bug or wrong architecture—check image for amd64/arm64. 127/126: fix entrypoint or add missing file. Run `docker run --rm -it image` to reproduce and confirm.

Done

Reviewed by Blackbox Atlas

Frequently asked questions

Why would a Docker container not start?
Exit code 0: app or entrypoint exited. Non-zero: crash, missing dependency, or OOM. Image pull failure, wrong entrypoint, missing env vars, or resource limits can also prevent start.
How do I see why a container exited?
Run docker logs container-name for stdout/stderr. Run docker inspect container-name and check State.ExitCode and State.Error. Run docker run with the same image and flags to reproduce.
When should I rebuild the image or contact support?
Rebuild when the entrypoint or base image is wrong. Contact support when you have logs and inspect output but the cause is unclear, or when the image is from a vendor and fails consistently.

Rate this guide

Was this helpful?

Continue to