Jenkins "Invalid agent type docker specified" Fix

TL;DR#

agent { docker { ... } } is not core Jenkins syntax — it is a declarative agent type that a plugin has to register. Without the Docker Pipeline plugin (ID docker-workflow) installed, the controller's pipeline parser does not recognise docker as a valid value at all, and the Jenkinsfile fails before a single step runs. Install Docker Pipeline (Manage Jenkins → Plugins → Available plugins → search "Docker Pipeline", then Install without restart, or restart if the plugin manager asks for it), and re-run the build. The Jenkinsfile itself does not need to change.

org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed:
WorkflowScript: 3: Invalid agent type "docker" specified. Must be one of [any, label, none] @ line 3, column 9.
           docker {
           ^

Why Jenkins rejects "docker" as an agent type#

Jenkins declarative pipelines only accept a small, fixed-looking list of top-level agent blocks out of the box: any, label and none. Every other agent type — docker, dockerfile, kubernetes — comes from a plugin that implements the DeclarativeAgent extension point and registers itself with the pipeline model.

The validator that raises this exact error lives in pipeline-model-definition-plugin, the plugin that actually implements the Declarative Pipeline syntax. Its message catalogue defines the error template verbatim:

ModelValidatorImpl.InvalidAgentType=Invalid agent type "{0}" specified. Must be one of {1}

{1} is built from whatever DeclarativeAgent extensions are currently registered on that controller — which is why the list in the error ([any, label, none]) grows the moment a plugin that adds another type is installed. The extension that adds docker (and dockerfile) lives in AbstractDockerAgent.java, part of the Docker Pipeline plugin (docker-workflow on plugins.jenkins.io). Until that plugin is on the controller, docker is simply not in the set the parser checks against, and the pipeline fails at Groovy compile time — before Jenkins even tries to contact a Docker daemon. This is the same failure a reader on Stack Overflow hit after moving a working Jenkinsfile from a local instance (which already had the plugin) to a fresh remote server (which did not).

Note that the Docker Pipeline plugin's name is easy to confuse with the separate Docker plugin (docker-plugin), which provisions cloud-managed build agents from Docker images and does not register this declarative agent type. Installing only docker-plugin leaves the error unchanged, because it never implements DeclarativeAgent.

Install Docker Pipeline#

1. Install the Docker Pipeline plugin. In the classic UI: Manage Jenkins → Plugins → Available plugins, search for "Docker Pipeline", tick it, and Install without restart (or restart afterwards if Jenkins asks for it).

Plugin: Docker Pipeline
Plugin ID: docker-workflow

2. If you provision Jenkins with Configuration as Code or a Docker image, pin it in the plugin list instead of clicking through the UI:

docker-workflow:latest

The plugin brings in docker-commons and pipeline-model-definition as dependencies, so a bare docker-workflow line is enough; you do not also need to list docker-plugin for this specific syntax.

3. Re-run the build. The same Jenkinsfile that failed now parses:

pipeline {
    agent {
        docker {
            image 'node:12.16.2'
            args '-p 3000:3000'
        }
    }
    stages {
        stage('Build') {
            steps {
                sh 'node --version'
                sh 'npm install'
                sh 'npm run build'
            }
        }
    }
}

This was reproduced on a throwaway Jenkins controller (jenkins/jenkins:lts-jdk17, Jenkins 2.541.3, Docker Pipeline plugin docker-workflow 653.v2f2c08eff0ec, 8 October 2026). With only workflow-aggregator installed, running this exact job produced:

Started by user admin
org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed:
WorkflowScript: 4: Invalid agent type "docker" specified. Must be one of [any, label, none] @ line 4, column 9.
           docker {
           ^
 
1 error
Finished: FAILURE

Rebuilding the identical image with one line added to the plugin list — docker-workflow:latest — and nothing else changed, then re-running the same job on a fresh container, produced a completely different console:

Started by user admin
[Pipeline] Start of Pipeline
[Pipeline] node
Running on Jenkins in /var/jenkins_home/workspace/repro-docker-agent
[Pipeline] {
[Pipeline] isUnix
[Pipeline] withEnv
[Pipeline] {
[Pipeline] sh
+ docker inspect -f . node:12.16.2
/var/jenkins_home/workspace/repro-docker-agent@tmp/durable-3701e8a1/script.sh.copy: 1: docker: not found
[Pipeline] isUnix
[Pipeline] withEnv
[Pipeline] {
[Pipeline] sh
+ docker pull node:12.16.2
/var/jenkins_home/workspace/repro-docker-agent@tmp/durable-e3e456bd/script.sh.copy: 1: docker: not found
[Pipeline] }
[Pipeline] // withEnv
[Pipeline] }
[Pipeline] // withEnv
[Pipeline] }
[Pipeline] // node
[Pipeline] End of Pipeline
ERROR: script returned exit code 127
Finished: FAILURE

The MultipleCompilationErrorsException is gone entirely — the Groovy parser accepted agent { docker {} } and the pipeline moved on to [Pipeline] node, then actually tried docker inspect and docker pull. Those two commands then failed with docker: not found, because this particular throwaway container has no docker CLI installed on the Jenkins controller itself — an unrelated, expected gap of this minimal repro (a real Jenkins Docker agent setup runs its builds on a node that has the docker binary and socket available, which is a separate prerequisite this article is not about).

Docker Pipeline, the Docker plugin, and Configuration as Code#

The accepted Stack Overflow answer tells readers to install "2 plugins: Docker plugin and Docker Pipeline" — in practice only Docker Pipeline (docker-workflow) is required for the agent { docker {} } syntax itself; it depends on docker-commons and pipeline-model-definition on its own, confirmed from the plugin's own dependency manifest. The separate Docker plugin (docker-plugin, whose update-centre summary reads "Provisions Jenkins agents on demand as Docker containers") solves a different problem — spinning up whole build agents from Docker images for a cloud — and installing it alone leaves this error unchanged, because it never implements the DeclarativeAgent extension point.

A third answer on the same question, aimed at readers who provision Jenkins through Configuration as Code rather than clicking through the UI, lists the plugin IDs to pin directly:

docker:latest
docker-commons:latest
docker-workflow:latest

Of those three, docker-workflow is the one that actually fixes this specific error, and docker-commons is a shared dependency it already pulls in. The first line is the odd one out: the Jenkins update centre has no plugin with the ID docker. The cloud-provisioning Docker plugin is published as docker-plugin, and it is only needed if the pipeline also provisions agents dynamically from images, which is a different feature from running one build step inside a container.

Verify the fix#

Check which plugins are actually active on the controller that runs the job, rather than trusting a plugin list you remember installing on a different one:

curl -s http://your-jenkins/pluginManager/api/json?depth=1 | grep -o '"shortName":"docker-workflow"'

An empty result means the plugin is not installed on that controller, no matter what the Jenkinsfile or a working instance elsewhere suggests — this is exactly the gap the original question hit: a Jenkinsfile that worked locally failed only after moving to a remote server with a different plugin set. The Jenkins classic UI shows the same fact under Manage Jenkins → Plugins → Installed plugins, filtered to "Docker Pipeline", with the installed version next to it. (The Advanced settings tab is not the place to look: per the Jenkins plugin management docs, it is where an .hpi file is uploaded by hand.)

The functional check is the build log itself: a run that gets past the "Invalid agent type" compilation error and instead reaches [Pipeline] node — even if a later step then fails for an unrelated reason, such as a missing Docker socket or CLI on that particular agent — confirms the declarative agent type is registered and this error will not recur for this Jenkinsfile. If the log still stops at MultipleCompilationErrorsException after a plugin install, confirm the install actually finished, and restart the controller if the plugin manager asks for it, before re-running the build — a queued install that has not completed yet changes nothing.

What breaks next, once the plugin is installed#

Getting past this one usually surfaces a real Docker problem next, because now Jenkins actually tries to run the image, on whichever agent the job lands on. In this repro, that next failure was docker: not found — a container with no Docker CLI on it at all. On a real Jenkins setup the agent that runs agent { docker {} } steps already has Docker, so the next failure is usually further along: the image pull, the container start, or a step inside it. If the agent on your Jenkins controller or build node has an old docker CLI, a flag that Docker Compose or a wrapper script passes can be rejected outright — see Fix Docker Compose "unknown flag: --iidfile" Build Error for how to tell a stale CLI binary from a real Compose problem. If the container starts but a step inside it (docker exec, or a tool the args line assumes exists) cannot find the binary it's looking for, that is a different, well-documented failure covered in Fix OCI runtime exec failed: executable file not found. And if Jenkins' own generated docker run invocation (or one you add by hand to debug the agent) puts a flag after the image name, see Docker 'OCI runtime create failed': a flag after the image for why that specific ordering mistake produces a runtime error that looks nothing like a syntax problem.

A Jenkinsfile that uses agent { docker {} } is a declarative shortcut for a real Docker workflow underneath, and every ordinary Docker failure — a missing binary, a stale CLI, a misplaced flag — can still show up once the declarative syntax itself is accepted. Fixing the plugin gap only clears the first gate.