🚨 Jenkins Error: 'java.lang.IllegalArgumentException: <step> is missing required parameter '<name>'' — Cause, Fix, and Troubleshooting Guide

Overview

A Pipeline step (or a parameterized build/trigger) was invoked without a mandatory argument. Jenkins validates step arguments before running the step, so it fails immediately with:

java.lang.IllegalArgumentException: publishHTML is missing required parameter 'target'
	at org.jenkinsci.plugins.structs.describable.DescribableModel.instantiate(DescribableModel.java:...)
	at org.jenkinsci.plugins.workflow.cps.DSL.invokeStep(DSL.java:...)

You will also see the plain-English variant Missing required parameter from parameterized builds and remote triggers when a downstream job declares a parameter that the caller did not supply. In both cases the fix is the same shape: provide the named argument, with the exact name the step or job expects.

Symptoms

• The build fails at a specific step (publishHTML, checkout, build, withCredentials, a plugin step) with is missing required parameter '<name>'.
• The named parameter matches a mandatory field of that step in the Pipeline Syntax reference.
• A build job: / remote-trigger step fails because the downstream job has a required parameter with no default.
• Manually triggering the same job through the UI works (you fill the form) but the automated trigger fails.
• Renaming or adding a parameter to a downstream job suddenly breaks upstream callers.

Common Root Causes

• Mandatory step argument omitted — e.g. publishHTML requires target; checkout requires SCM fields; a plugin step requires a specific key you left out.
• Wrong argument name (typo or renamed key) — the step expects reportDir but you passed dir, or a plugin upgrade renamed a field.
• checkout scm used where no SCM is bound — a Pipeline-from-SCM job provides scm, but a pasted inline script has nothing bound, so the required remote/branch fields are missing.
• Parameterized downstream job missing a value — build job: 'deploy' doesn’t pass a parameter the deploy job marks required and has no default for.
• Remote build trigger without the parameter — the “Trigger builds remotely”/Parameterized Remote Trigger call omits a required query parameter.
• parameters{} declared but never passed on trigger — a scheduled/webhook trigger fires the job without the parameters the job requires.

How to diagnose

Read the step name and parameter name from the exception — <step> is missing required parameter '<name>' tells you exactly which argument to add.

Confirm the correct argument names from the built-in reference: open the job → Pipeline Syntax (Snippet Generator) or Global Variable Reference, select the step, and generate a correct invocation. This is authoritative for the installed plugin version.

For a downstream/parameterized job, list its declared parameters:

// Manage Jenkins → Script Console
def job = Jenkins.instance.getItemByFullName('deploy')
def pd  = job.getProperty(hudson.model.ParametersDefinitionProperty)
pd?.parameterDefinitions.each {
    println "${it.name} (${it.class.simpleName}) default=${it.defaultParameterValue?.value}"
}

Any parameter with a null/absent default is effectively required from an automated caller. Check the console log of the upstream build to see what it actually passed, and inspect the trigger config in Configure → Build Triggers.

Fixes

1. Supply the missing step argument

Add the named parameter using the exact key from Pipeline Syntax. Example for publishHTML, whose target is a nested object:

publishHTML(target: [
    reportName : 'Coverage',
    reportDir  : 'build/coverage',
    reportFiles: 'index.html',
    keepAll    : true,
    alwaysLinkToLastBuild: true,
    allowMissing: false
])

2. Give checkout all required SCM fields (or use scm)

If you cannot rely on checkout scm, provide the mandatory userRemoteConfigs and branches:

checkout([
    $class: 'GitSCM',
    branches: [[name: '*/main']],                       // required
    userRemoteConfigs: [[                               // required
        url: 'git@jenkins.example.com:team/app.git',
        credentialsId: '<credentials-id>'
    ]]
])

3. Pass required values when triggering a downstream job

Provide every required parameter in the build step’s parameters: list, matching names and types:

build job: 'deploy',
      parameters: [
          string(name: 'ENVIRONMENT', value: 'staging'),
          string(name: 'VERSION', value: env.BUILD_NUMBER),
          booleanParam(name: 'RUN_SMOKE_TESTS', value: true)
      ],
      wait: true

4. Declare the parameters (with sensible defaults) on the job

Make the job’s contract explicit and give defaults so automated triggers don’t fail:

pipeline {
    agent any
    parameters {
        string(name: 'ENVIRONMENT', defaultValue: 'staging', description: 'Target env')
        string(name: 'VERSION',     defaultValue: 'latest',   description: 'Artifact version')
    }
    stages {
        stage('Deploy') {
            steps { sh "deploy.sh ${params.ENVIRONMENT} ${params.VERSION}" }
        }
    }
}

A parameter with a defaultValue is no longer “missing” when a trigger omits it.

5. Include required parameters on remote/parameterized triggers

For the Parameterized Remote Trigger plugin (or a raw buildWithParameters call), pass every required parameter in the query string:

curl -X POST "https://jenkins.example.com/job/deploy/buildWithParameters?ENVIRONMENT=prod&VERSION=1.4.2" \
     --user "<user>:<api-token>"

What to watch out for

• Parameter names are case-sensitive and must match exactly — Version and VERSION are different parameters.
• Adding a required parameter (no default) to a downstream job silently breaks every upstream caller — add a default, or update all callers in the same change.
• The correct argument names change between plugin versions; regenerate from Pipeline Syntax after upgrades rather than trusting old snippets.
• A required nested object (like publishHTML(target: [...])) fails the same way if the object is present but missing one of its required keys — read the full parameter path.
• checkout scm only works in a job whose definition comes from SCM; inline “Pipeline script” jobs must specify the SCM fields explicitly.

Related

• Jenkins Error: ‘No such DSL method’ — when the step name itself, not just its parameter, is wrong or unrecognized.
• Jenkins Error: ‘groovy.lang.MissingPropertyException: No such property’ — the related failure when a referenced params.X or variable doesn’t exist.
• Jenkins Error: ‘Could not find credentials with ID’ — a specific “missing required value” case for the credentialsId argument.