Opscraft
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, post blocks.
  • 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 diagramSnippet Generatorsyntax for any stepLintervalidate before pushingReplayedit and re-run, no commitRestart from stageskip what already passedGraph Viewfind the slow stageDirective Generatoroptions, when, post
Figure 1. Tools to write and debug Jenkinsfiles faster.
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

  1. Measure stage durations first.
  2. Run independent checks in parallel.
  3. Cache dependencies (Maven/npm proxies, cache volumes), Docker layers (registry cache).
  4. Smaller, pre-pulled agent images; warm node pools for pod agents.
  5. Only build/test what changed (changeset in monorepos).
  6. Split slow test suites and move long E2E suites to nightly or post-merge.
  7. abortPrevious for superseded PR builds.
Enlarge diagramMeasurestage timingsfirstParallelindependentchecksCachedependencies,Docker layersSmaller agentspre-pulledimagesLess workonly whatchanged; E2Enightly12345
Figure 2. Speeding up a slow pipeline, in the order to try.
Swipe sideways to see all of it, or tap to open it full screen.