When Something Won't Start

A container that will not start is the normal state of learning Docker, not a sign that you did something wrong. The commands you used so far already show most of the answers. The trick is to ask them in the right order, and not to restart things hoping for a different result. This lesson goes through the failures you will meet most often, with the real message for each.

A checklist you can repeat

1. Is Docker itself running? If docker ps fails, nothing else matters yet.
2. Did the container start at all? docker ps -a shows it, with an exit code.
3. What did it say? docker logs <name>.
4. If the log is empty, what does Docker say about the container? docker inspect.
5. Only then change something, one thing at a time, and run it again.

Docker is not running

If Docker Desktop is closed or still starting, every command fails with the same kind of message. The one below was produced by pointing the command at a pipe that does not exist. On your machine the pipe name in the message will be dockerDesktopLinuxEngine.

docker -H npipe:////./pipe/doesNotExist ps

failed to connect to the docker API at npipe:////./pipe/doesNotExist; check if the path is correct and if the daemon is running: open //./pipe/doesNotExist: The system cannot find the file specified.

The fix is on the Windows side: start Docker Desktop and wait until it says the engine is running. If it never gets there, use the tutorial "Fix Docker Desktop Stuck on Starting".

The container exits at once

docker run -d --name quick alpine:3.24

docker ps -a --filter name=quick --format "table {{.Names}}\t{{.Status}}"
docker logs quick

NAMES     STATUS
quick     Exited (0) 2 seconds ago

"Exited (0)" with an empty log is not a failure. Alpine's default command is a shell, and a shell with no keyboard attached exits right away. A container lives only as long as its main process. A web server stays up because it keeps running. A command that finishes takes the container with it. If you wanted it to stay, run a program that keeps running, or give the shell a terminal with -it.

The command does not exist

docker run --name nosuch alpine:3.24 nosuchcommand
docker inspect nosuch --format "exit {{.State.ExitCode}}: {{.State.Error}}"

docker: Error response from daemon: failed to create task for container: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: error during container init: exec: "nosuchcommand": executable file not found in $PATH

Run 'docker run --help' for more information
exit 127: failed to create task for container: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: error during container init: exec: "nosuchcommand": executable file not found in $PATH

Exit code 127 and "executable file not found" is almost always a typo in the command, or a program that is not in that image. A tiny image like Alpine has few tools. The fix is to check the command in a shell inside the same image, and to remember that Alpine has sh but usually not bash.

The image or tag does not exist

docker pull nginx:no-such-tag

Error response from daemon: failed to resolve reference "docker.io/library/nginx:no-such-tag": docker.io/library/nginx:no-such-tag: not found

"Not found" for a tag means the name or the version is wrong. Check the spelling on Docker Hub. A private image gives a different message about access, and for that you need to sign in to the registry.

The name or the port is taken

You met both in lesson 3: the name conflict and "port is already allocated". The fix is to pick another name or another host port, or to remove the container that owns it. docker ps -a shows who owns the name, and docker ps shows who owns the port.

The out-of-memory kill

A container that exits with code 137 was killed. The most common reason is that it used more memory than it was allowed. docker inspect answers it directly, with {{.State.OOMKilled}}. If it says true, give Docker Desktop more memory in Settings, under Resources, or fix the program. I could not reproduce this safely for the lesson, so the output is not shown. The command is the same as above.

docker rm -f quick nosuch

A container exits with code 0 and prints nothing. Is that a bug, and what would you check first?