Jenkinsfile · Lesson 9 of 10 · 4 min read
Tooling, debugging and common errors
Tools that save time
- Snippet Generator (job → Pipeline Syntax) — generates step syntax for any installed plugin.
- Declarative Directive Generator — generates
options,when,agent,postblocks. - Declarative linter — validate before pushing:
curl -s -X POST -u "$USER:$API_TOKEN" -F "jenkinsfile=<Jenkinsfile" https://jenkins.example.com/pipeline-model-converter/validate
# or: java -jar jenkins-cli.jar -s https://jenkins.example.com declarative-linter < Jenkinsfile
IDE plugins (VS Code Jenkins Pipeline Linter) call the same endpoint.
- Replay — edit and rerun a build's Jenkinsfile (and library code) without committing; perfect for debugging, not for permanent changes.
- Restart from Stage — rerun a declarative pipeline from a chosen stage, reusing earlier results (needs preserveStashes if later stages unstash).
- Pipeline Steps / Pipeline Graph View — per-step timings and logs; find slow stages.
Enlarge diagram
Swipe sideways to see all of it, or tap to open it full screen.
Common errors
| Error | Meaning / fix |
|---|---|
Expected a step / Unknown stage section |
Declarative structure wrong — steps outside steps {}, Groovy outside script {} |
No such DSL method 'xyz' |
Plugin providing the step isn't installed, or a library isn't loaded |
Scripts not permitted to use method ... |
Sandbox rejection — use a step or get admin approval (carefully) |
NotSerializableException |
Non-serializable object held across a step — use @NonCPS helpers |
groovy.lang.MissingPropertyException: No such property: FOO |
Used an undefined variable — maybe meant env.FOO or params.FOO |
| Variable empty in a later stage | Declared with def inside one script {} — use env.X |
| Parameters missing in UI | Run the branch once so Jenkins reads the parameters block |
| Secret warning about Groovy interpolation | Switch sh "...${SECRET}..." to single quotes |
| Approval stage holds a pod for hours | input inside an agent — use agent none + input directive |
| Two deploys run at once | disableConcurrentBuilds() or lock the environment |
| Build "succeeded" but tests failed | junit marks UNSTABLE, not FAILURE — decide whether unstable should block deploys (when { expression { currentBuild.currentResult == 'SUCCESS' } }) |
Speeding up a slow pipeline
- Measure stage durations first.
- Run independent checks in parallel.
- Cache dependencies (Maven/npm proxies, cache volumes), Docker layers (registry cache).
- Smaller, pre-pulled agent images; warm node pools for pod agents.
- Only build/test what changed (
changesetin monorepos). - Split slow test suites and move long E2E suites to nightly or post-merge.
abortPreviousfor superseded PR builds.
Enlarge diagram
Swipe sideways to see all of it, or tap to open it full screen.