Maaz Zindani

Loading the index…

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

A Jenkins pipeline stage that runs docker cannot find the docker command

Errorsh step in the pipeline reports that docker is not found

Short answer

Jenkins in a container ships without the Docker client, so a sh step that calls docker fails. Check three things: the docker CLI exists inside the Jenkins image, the CLI can reach a daemon through DOCKER_HOST, and the Docker Pipeline plugin is installed for agent { docker }. Fix whichever one is missing.

  • Applies to Jenkins LTS 2.5xx, Docker Engine 27, Docker Pipeline plugin (docker-workflow)
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open a shell in the running Jenkins container and ask whether the CLI is there and where it points.

    docker exec -it jenkins bash -c 'which docker; docker version; echo "DOCKER_HOST=$DOCKER_HOST"'
  2. 2Match what you see, then jump to its fix

    1. 1which docker prints nothing inside the containerThe Jenkins image has no Docker CLIFix
    2. 2docker --version works, docker version fails on the server partThe CLI is installed but has no daemon to talk toFix
    3. 3Only agent { docker { ... } } fails; plain sh steps that call docker are fineThe Docker Pipeline plugin is missingFix

What does the error look like?

  • sh step in the pipeline reports that docker is not found
  • Jenkins cannot use the docker agent type in Declarative Pipeline

Cause 1 of 3

The Jenkins image has no Docker CLI

1Check

The official jenkins/jenkins image does not include the Docker client. Pipeline steps run inside that container, so they only see what the image holds.

docker exec jenkins which docker

2Fix

Build your own image from the official one and install docker-ce-cli from Docker's apt repository, as the Jenkins install guide does. Run the new image in place of the old one.

FROM jenkins/jenkins:2.580.2-jdk21
USER root
RUN apt-get update && apt-get install -y lsb-release ca-certificates curl && \
    install -m 0755 -d /etc/apt/keyrings && \
    curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc && \
    chmod a+r /etc/apt/keyrings/docker.asc && \
    echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo \"$VERSION_CODENAME\") stable" \
    | tee /etc/apt/sources.list.d/docker.list > /dev/null && \
    apt-get update && apt-get install -y docker-ce-cli && \
    apt-get clean && rm -rf /var/lib/apt/lists/*
USER jenkins

3Verify

Build the image, start a container from it and run the client.

docker build -t myjenkins:2.580.2-1 .
docker run --rm myjenkins:2.580.2-1 docker --version

Confirmed by jenkins.io

Did this fix it?

Cause 2 of 3

The CLI is installed but has no daemon to talk to

1Check

A client alone does nothing. In the Jenkins guide the controller reaches a separate docker:dind daemon over TCP, driven by three environment variables. If they are missing from your docker run, the client finds no daemon.

docker exec jenkins env | grep DOCKER

2Fix

Run the docker:dind container on a shared network with the alias docker, then start Jenkins on the same network with DOCKER_HOST, DOCKER_CERT_PATH and DOCKER_TLS_VERIFY and the shared certs volume mounted read-only.

docker network create jenkins
docker run --name jenkins-docker --rm --detach \
  --privileged --network jenkins --network-alias docker \
  --env DOCKER_TLS_CERTDIR=/certs \
  --volume jenkins-docker-certs:/certs/client \
  --volume jenkins-data:/var/jenkins_home \
  --publish 2376:2376 \
  docker:dind --storage-driver overlay2
docker run --name jenkins --restart=on-failure --detach \
  --network jenkins --env DOCKER_HOST=tcp://docker:2376 \
  --env DOCKER_CERT_PATH=/certs/client --env DOCKER_TLS_VERIFY=1 \
  --publish 8080:8080 --publish 50000:50000 \
  --volume jenkins-data:/var/jenkins_home \
  --volume jenkins-docker-certs:/certs/client:ro \
  myjenkins:2.580.2-1

3Verify

The client now sees a server.

docker exec jenkins docker version

Confirmed by jenkins.io

Did this fix it?

Cause 3 of 3

The Docker Pipeline plugin is missing

1Check

The Jenkins docs say that without the Docker Pipeline plugin, Jenkins cannot use the docker agent type in Declarative Pipeline. In Manage Jenkins, Plugins, Installed plugins, look for Docker Pipeline.

# Manage Jenkins > Plugins > Installed plugins: search for Docker Pipeline

2Fix

Install the plugin in the image so it survives rebuilds, then rebuild and restart.

# last line of the Dockerfile, after USER jenkins
RUN jenkins-plugin-cli --plugins "docker-workflow json-path-api"

3Verify

Run a pipeline that uses the docker agent; the stage starts the container and runs its steps inside it.

pipeline {
  agent { docker { image 'node:22-alpine' } }
  stages { stage('Test') { steps { sh 'node --version' } } }
}

Confirmed by jenkins.io

Did this fix it?

How do I stop it coming back?

  • Keep the Jenkins Dockerfile in version control and pin the base image tag.
  • List plugins in the Dockerfile with jenkins-plugin-cli so a rebuild never drops one.
  • Use named volumes for jenkins-data and the certs, so replacing the container loses nothing.

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.