Pipeline builds using docker.image.inside fail after upgrade

Article ID:360046926092
2 minute readKnowledge base


After upgrading the Docker Pipeline plugin to version 1.15 or newer, Pipeline builds that use a docker.image.inside{} block start failing with the following error:

ERROR: The container started but didn't run the expected command. Please double check your ENTRYPOINT does execute the command passed as docker run argument, as required by official docker images (see https://github.com/docker-library/official-images#consistency for entrypoint consistency requirements).
Alternatively you can force image entrypoint to be disabled by adding option --entrypoint=''.

This issue only affects some containers that define a custom ENTRYPOINT.


docker.image.inside and the other features of the Docker Pipeline plugin are meant to be used to run a container which has some tools pre-installed, and then execute your build steps as a shell script inside that container. If the container you specify has an ENTRYPOINT process that runs a daemon or other process that never exits, control of the container shell is never returned to Jenkins and so your job’s shell steps aren’t able to run.

In older versions of Docker Pipeline the plugin passed --entrypoint alone to override any built-in container entrypoint, and then passed --entrypoint cat to explicitly set cat as the entrypoint. In other words, the command being run was docker run -d -t --entrypoint='' --entrypoint cat ... Newer versions of the Docker tools no longer allow more than one --entrypoint argument, and it was decided that the plugin should not forcibly override a container’s defined ENTRYPOINT because this would remove control over that setting from the user. As a result, if you are affected by this issue you will either need to change your container definition in your Dockerfile, or change the configuration of your Pipeline jobs.

If the entrypoint you have defined for your container is not required to get your build to run, you can override it in your Pipeline code like this:

docker.image('user/image:version').inside("""--entrypoint=''""") {
    // some steps here

Alternatively, you can change your Dockerfile to either remove the ENTRYPOINT if it is not needed, or change the ENTRYPOINT line to CMD if that doesn’t cause other issues in your process. If you change to CMD, Docker Pipeline will override that and run cat as the CMD so that the plugin can communicate with the container.

For cases where you want to run a sidecar container (such as to start up a network service like an HTTP server) while your build continues in a separate context, it’s recommended that you just execute docker commands directly in shell steps, rather than using the docker.image.inside syntax.

Tested product/plugin versions

Docker Pipeline plugin version 1.15 or newer.