Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

A Docker container will not run its entrypoint.sh script

Errorpermission denied

Short answer

Most often the script was copied into the image without the execute bit, so the kernel refuses to run it. Set the mode when you copy it, and keep the bit in Git. Two other causes look similar: a bind mount can hide the image's copy of the script, and shell-form ENTRYPOINT ignores CMD arguments.

  • Applies to Docker Engine 28, Docker Buildx 0.2x, Git 2.4x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Look at the file inside the image, bypassing the entrypoint. The mode column shows whether the execute bit is set.

    docker run --rm --entrypoint ls my-image -l /usr/local/bin/docker-entrypoint.sh
    docker inspect --format '{{ .Config.Entrypoint }}' my-image
  2. 2Match what you see, then jump to its fix

    1. 1ls -l shows -rw-r--r-- with no x, and starting the container ends in permission denied.The script is in the image without the execute bitFix
    2. 2The image works alone, but fails or runs an old script when the same folder is mounted with -v or a compose volume.A bind mount hides the script that was baked into the imageFix
    3. 3The script starts, but the command after the image name in docker run, or CMD, never reaches it, or the program does not react to docker stop.Shell-form ENTRYPOINT ignores the arguments you passFix

What does the error look like?

  • permission denied
  • the container exits at once and the entrypoint script does not run

Cause 1 of 3

The script is in the image without the execute bit

1Check

COPY keeps the mode of the file in your build context. A file saved without x, or checked out on a system that does not track modes, arrives without x.

ls -l docker-entrypoint.sh

2Fix

Set the mode in the Dockerfile with the COPY --chmod flag, which takes octal or symbolic values. Also record the bit in Git so every checkout has it.

COPY --chmod=755 docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
ENTRYPOINT ["docker-entrypoint.sh"]

# once, in the repository
git update-index --chmod=+x docker-entrypoint.sh

3Verify

The bit is set in the rebuilt image and the container starts.

docker build -t my-image .
docker run --rm --entrypoint ls my-image -l /usr/local/bin/docker-entrypoint.sh

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

A bind mount hides the script that was baked into the image

1Check

A bind mount over a folder that already has files in the image hides those files. If the host folder has its own copy of the script, that copy is used, with whatever mode it has.

docker inspect --format '{{ json .Mounts }}' my-container

2Fix

Mount over a different path than the one that holds the script, or fix the file on the host. Removing the mount shows the image's own files again.

# compose.yaml: keep the script's folder out of the mount
services:
  app:
    image: my-image
    volumes:
      - ./src:/app/src

3Verify

Start the container with the changed volumes.

docker compose up app

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

Shell-form ENTRYPOINT ignores the arguments you pass

1Check

Shell form runs the entrypoint as a subcommand of /bin/sh -c. It ignores CMD and docker run arguments, and the program is not PID 1, so it does not receive SIGTERM.

grep -n "^ENTRYPOINT\|^CMD" Dockerfile

2Fix

Use exec form, and call exec at the end of the script so the final process takes over as PID 1.

ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["server", "--port", "8080"]

# last line of docker-entrypoint.sh
exec "$@"

3Verify

Arguments reach the script.

docker run --rm my-image server --port 9090

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Use COPY --chmod for every script copied into an image, so the build does not rely on file modes from the checkout.
  • Keep scripts on a filesystem that tracks the execute bit, or set it with git update-index --chmod=+x.
  • Write ENTRYPOINT in exec form and keep the default arguments in CMD.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.