Why Won't My Docker Container Start?

How the Docker start error analyzer works

A container can fail before the image process runs, during process startup, or after the application begins executing. This tool matches common daemon, OCI runtime, mount, port, resource, and process-exit signatures. It then suggests commands that inspect the current image, container, and Compose configuration rather than relying on the Dockerfile alone.

Collect the container state and effective configuration

docker inspect your-container --format '{{json .State}}'
docker image inspect your-image --format '{{json .Config}}'
docker compose config
docker logs your-container --tail 200

Compose interpolation, command overrides, bind mounts, and platform selection can change what actually runs. The rendered configuration and the container state reveal those runtime values.

When there are no application logs

Errors such as exec format error, executable file not found, and entrypoint permission failures occur before the application can write a log. Inspect image architecture, ENTRYPOINT, CMD, the entrypoint shebang, line endings, and executable mode. Also check whether a bind mount replaces a valid file from the image with a different host file.

When the process starts and exits

An exit code is evidence, not a complete cause. Code 137 often represents SIGKILL and should be paired with the container's OOMKilled value. Code 127 usually means a command could not be found, while code 126 commonly indicates that a command was found but could not be executed. Application-specific codes still require the application's own logs and documentation.

Do not erase the evidence first

Avoid pruning images, volumes, and containers before inspecting them. Cleanup can remove the exact configuration and state needed to explain the failure. Capture inspect output and logs first, then rebuild or recreate the service deliberately.