Docker "failed to set up exec" (entrypoint shell missing in scratch) in CI

By Kaveh Alemi·Latchkey

Shell-form CMD foo or ENTRYPOINT foo runs as /bin/sh -c "foo". A scratch or distroless image has no shell, so the runtime cannot set up the exec and the container fails to start. The fix is to use exec form (a JSON array) that invokes the binary directly.

What this error means

A container built FROM scratch (or a distroless base) fails to start with an exec/setup error pointing at a missing /bin/sh.

docker: Error response from daemon: failed to create task for container: failed to set up exec /bin/sh: no such file or directory: unknown.

Common causes

Shell-form CMD/ENTRYPOINT on a shell-less base

Shell form needs /bin/sh, which scratch and distroless images do not include.

A static binary that still relies on shell form

Even a self-contained binary cannot be launched via shell form when no shell exists.

How to fix it

Use exec form to call the binary directly

1. Write ENTRYPOINT/CMD as a JSON array so no shell is needed.

FROM scratch
COPY --chmod=755 app /app
ENTRYPOINT ["/app"]
CMD ["--port", "8080"]

Add a shell if you need shell features

1. If the entrypoint truly needs shell expansion, base on a minimal image that ships /bin/sh.

FROM alpine:3.20
COPY --chmod=755 app /app
ENTRYPOINT ["/bin/sh", "-c", "/app --port $PORT"]

How to prevent it

• Use exec-form CMD/ENTRYPOINT for scratch and distroless images.
• Reserve shell form for bases that actually include a shell.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation