🚨 Jenkins Error: 'java.lang.NoSuchMethodError: No such DSL method '<step>' found among steps' — Cause, Fix, and Troubleshooting Guide

Overview

Your pipeline compiles fine but blows up the moment it tries to invoke a step that Jenkins doesn’t recognize. The build log shows a runtime error naming the step and, helpfully, a long list of the steps Jenkins does know about:

java.lang.NoSuchMethodError: No such DSL method 'sshagent' found among steps [archiveArtifacts, bat, build, catchError, checkout, deleteDir, dir, echo, error, fileExists, git, input, isUnix, junit, mail, node, parallel, powershell, pwd, readFile, retry, sh, sleep, stage, stash, timeout, tool, unstash, waitUntil, withCredentials, withEnv, writeFile, ws, ...]

Almost always this means the plugin that provides the step isn’t installed, the step name is misspelled, or you’re calling the step in a context where it isn’t valid (for example outside a steps block, or outside the block that scopes it).

Symptoms

• The build reaches a stage, then fails with No such DSL method '<step>' found among steps [...].
• The bracketed list of known steps does not contain the step you called.
• A Jenkinsfile that runs on one controller fails on another with fewer plugins.
• Steps like sshagent, withAWS, dockerfile, container, or nodejs fail while core steps (sh, echo) work.
• The step works inside one wrapper but fails when moved outside it.
• A recently written declarative pipeline rejects a directive you put in the wrong place.

Common Root Causes

• Plugin not installed — sshagent needs SSH Agent plugin, withAWS needs Pipeline: AWS Steps, dockerfile/docker needs Docker Pipeline, container needs Kubernetes plugin, nodejs needs NodeJS plugin.
• Typo or wrong casing — withCredentials vs withcredentials, archiveArtifacts vs archiveArtifact. Step names are case-sensitive.
• Step only valid inside a specific block — container(...) is only available inside a Kubernetes podTemplate/agent; withAWS wraps a closure and can’t be called bare.
• Called outside a steps block — in declarative pipelines, steps must live inside steps { } (or script { }), not directly under stage.
• Declarative vs scripted confusion — scripted constructs (node {}, free Groovy) placed in a declarative pipeline, or a declarative directive used in scripted.
• Plugin installed but controller not restarted — the step isn’t registered until the plugin finishes loading.
• Version mismatch — the step was renamed or added in a newer plugin version than the one installed.

How to diagnose

Start by reading the bracketed list in the error — it’s the authoritative set of steps currently registered. If your step isn’t there, it’s a missing plugin or a typo, not a context issue.

Confirm whether the step exists anywhere on the controller from the Script Console (Manage Jenkins → Script Console):

// List every registered pipeline step and whether ours is present
def target = 'sshagent'
def steps = org.jenkinsci.plugins.workflow.steps.StepDescriptor.all()
  .collect { it.functionName }.sort()
println "Total steps: ${steps.size()}"
println steps.contains(target) ? "'${target}' IS registered" : "'${target}' is MISSING"
println steps.join(', ')

Check which plugin should provide it. The built-in Pipeline Syntax → Steps Reference page (<jenkins>/pipeline-syntax/ on any pipeline job) documents every available step and its owning plugin.

List installed plugins to confirm presence and version:

// Script Console: find the plugin that ships the step
Jenkins.instance.pluginManager.plugins
  .findAll { it.shortName in ['ssh-agent', 'pipeline-aws', 'docker-workflow', 'kubernetes', 'nodejs'] }
  .each { println "${it.shortName} ${it.version} enabled=${it.isEnabled()}" }

Fixes

1. Install the plugin that provides the step

Map the step to its plugin, install via Manage Jenkins → Plugins → Available, and restart the controller if prompted:

Step	Plugin
sshagent	SSH Agent
withAWS, s3Upload	Pipeline: AWS Steps
docker, dockerfile	Docker Pipeline
container, podTemplate	Kubernetes
nodejs	NodeJS
withVault	HashiCorp Vault

2. Fix the step name

Match the exact function name from the Steps Reference. Correct usage of a wrapper step passes a closure:

pipeline {
  agent any
  stages {
    stage('Deploy') {
      steps {
        sshagent(credentials: ['deploy-key']) {
          sh 'ssh deploy@app-01 "systemctl restart app"'
        }
      }
    }
  }
}

3. Call context-scoped steps inside their block

container only exists inside a Kubernetes agent; withAWS must wrap the code that needs the credentials:

pipeline {
  agent {
    kubernetes {
      yaml '''
        spec:
          containers:
          - name: aws
            image: amazon/aws-cli:2
            command: [sleep]
            args: ["infinity"]
      '''
    }
  }
  stages {
    stage('S3') {
      steps {
        container('aws') {                 // valid only inside k8s agent
          withAWS(region: 'us-east-1', credentials: 'aws-ci') {
            sh 'aws s3 ls s3://my-bucket/'
          }
        }
      }
    }
  }
}

4. Keep steps inside a steps (or script) block

Declarative pipelines reject bare steps under stage. Wrap them:

// WRONG — step directly under stage
stage('Build') { sh 'make' }

// RIGHT — step inside steps{}
stage('Build') {
  steps { sh 'make' }
}

Use script { } only when you genuinely need imperative Groovy inside a declarative stage.

5. Restart after installing

After installing a step-providing plugin, use Manage Jenkins → Plugins → check “Restart Jenkins when installation is complete and no jobs are running”, or restart the service so the step registers.

What to watch out for

• Treat the bracketed step list as ground truth — if the step isn’t listed, no amount of syntax fiddling will help until the plugin is installed.
• Pin plugin versions in your controller-as-code (JCasC / plugins.txt) so a step doesn’t vanish when an environment is rebuilt.
• Wrapper steps (sshagent, withAWS, withCredentials, container) always take a closure — calling them without { ... } silently does nothing useful or errors.
• Don’t mix scripted node {} blocks into a declarative pipeline {}; keep imperative code inside script {}.
• Browse the per-job Pipeline Syntax → Snippet Generator to get the exact, version-correct invocation for any installed step.
• Curating the Jenkins guides in one place helps — see the Jenkins troubleshooting hub.

Related

• Jenkins Error: ‘unable to resolve class’ — the compile-time twin, when an imported class (not a step) is missing.
• Jenkins Error: ‘Scripts not permitted to use method’ — sandbox rejection you hit after the step is installed but calls a blocked signature.
• Jenkins Error: ‘Could not find credentials entry with ID’ — common next failure once withCredentials/withAWS resolve.