16.2.1.2 Runtime Command Error

A runtime command error occurs when the command Docker attempts to execute as a container's entrypoint or main process fails at the moment of invocation itself, distinct from an application-level error that occurs after the process has successfully started, and these errors are reported directly by the Docker daemon rather than by the application, which gives them a recognizable, consistent format worth learning to read quickly.

Recognizing the daemon's own error format

When Docker itself cannot successfully start the configured command, it reports the failure directly, typically before any application code has had a chance to run at all:

docker run my-api

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:
exec: "node": executable file not found in $PATH: unknown.

This layered error message, originating from several levels of the container runtime stack (the daemon, the shim, the OCI runtime), can look intimidating, but the actually relevant detail is almost always at the very end: here, executable file not found in $PATH, which immediately identifies the actual problem regardless of how many wrapping layers of infrastructure reported it.

Command not found errors

The most common runtime command error is a reference to a binary that does not exist at the specified path or under the specified name inside the image:

CMD ["pyhton", "app.py"]

exec: "pyhton": executable file not found in $PATH

A typo in the command name itself, as in this example, is a frequent and simple cause; verifying the exact, correct binary name and confirming it is actually installed and on the PATH inside the image resolves this directly:

docker run --rm my-api:1.4.0 which python3

Working directory does not exist

A WORKDIR instruction referencing a directory that was never actually created, either because an earlier instruction expected to create it failed silently or was never included at all, produces a runtime error when the container attempts to start with a working directory that does not exist:

WORKDIR /app/nonexistent

exec: "node": stat /app/nonexistent: no such file or directory

Confirming the working directory actually exists in the built image, rather than assuming a WORKDIR instruction always succeeds in creating it (it does create the directory if missing during the build itself, but a runtime override or a different stage's filesystem state can produce a mismatch), resolves this category of error.

Entrypoint script issues

A script specified as ENTRYPOINT that has the wrong shebang line, references an interpreter not present in the image, or was not made executable, produces a runtime command error distinct from, but related to, the script's own internal logic:

COPY entrypoint.sh /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]

exec /entrypoint.sh: no such file or directory

This specific error, despite the file clearly being copied, often indicates the script's shebang line references an interpreter that does not exist at that path inside the image, for instance #!/bin/bash in an image that only has /bin/sh available, which produces a confusing "no such file or directory" error referring to the script itself rather than clearly indicating the actual missing interpreter:

docker run --rm my-api:1.4.0 cat /entrypoint.sh | head -1
docker run --rm my-api:1.4.0 ls -la /bin/bash

Checking the script's shebang line against what is actually available inside the image directly resolves this ambiguity.

Argument and array syntax issues

A CMD or ENTRYPOINT instruction using exec-form (JSON array) syntax incorrectly, with a typo in the array structure or an unexpected mixing of shell and exec form, can produce a runtime error that looks like a command-not-found issue but is actually a malformed instruction:

CMD ["node" "server.js"]

error parsing reference for repository... invalid argument

A missing comma between array elements, as in this example, produces a build-time or runtime parsing error depending on exactly how the malformation manifests; carefully reviewing the exact JSON array syntax, valid, comma-separated, double-quoted strings, resolves syntax-level issues like this one.

Distinguishing runtime command errors from application startup errors

It is worth being precise about the boundary here: a runtime command error means Docker itself could not even successfully invoke the configured command; once the command does successfully start executing, any subsequent failure, even one that happens within milliseconds, is an application-level startup error, not a runtime command error, and the diagnostic approach for the latter (checking application logs, configuration, dependencies) differs from the former (checking the command's existence, permissions, and syntax):

docker logs my-api

If docker logs shows actual application output before the failure, even briefly, the command itself was successfully invoked, and the problem lies in what the application did after starting, not in the command invocation itself.

Verifying a fix interactively before redeploying

Once a suspected fix is identified, confirming it directly through an interactive session, rather than rebuilding and redeploying immediately, provides faster iteration and more certainty before committing to a full rebuild cycle:

docker run -it --rm --entrypoint sh my-api:1.4.0

node server.js

Manually running the exact intended command from within this interactive shell session validates the fix directly against the actual image contents before finalizing the corresponding Dockerfile change.

Common mistakes

• Being intimidated by the daemon's layered, verbose error message rather than focusing on the specific, actually relevant detail typically found at the very end of it.
• Not distinguishing between a runtime command error (Docker could not invoke the command at all) and an application-level startup error (the command ran but the application itself then failed).
• Assuming a copied script will execute correctly without verifying its shebang line references an interpreter that actually exists inside the specific image being used.
• Overlooking JSON array syntax errors in exec-form CMD or ENTRYPOINT instructions, mistaking a syntax problem for a missing-command problem.
• Rebuilding and redeploying to test a suspected fix rather than verifying it more quickly through an interactive session first.

Runtime command errors are reported directly and consistently by the container runtime stack, and reading past the layered, verbose wrapping to the specific, actionable detail at the end of the message, combined with verifying the exact command, path, and script interpreter actually present inside the image, resolves the large majority of these errors quickly and without ambiguity.