Pipeline Steps, Error Handling, retry, timeout, catchError, input, waitUntil, and Resilient Flow Control: Diagnostics, Failure Modes, Security, and Performance

1. Evidence-first diagnostic sequence

1. Preserve job full name, build/queue IDs, URL, cause, exact source/Jenkinsfile SHA, result, and the first failing console excerpt.
2. Confirm controller/core/Java and Pipeline plugin baseline.
3. Confirm the failing stage/step and whether it ran inside a node/workspace.
4. Inspect exception type: ordinary failure, timeout/interruption, agent loss, or user abort.
5. Count retry attempts and identify exactly which body was repeated.
6. Check whether catchError changed build/stage result or swallowed interruption semantics.
7. Inspect approver identity and whether an agent was held during input.
8. Inspect polling duration/recurrence and outer timeout.
9. Verify external target state independently before retrying or rerunning.
10. Apply the smallest correction and rerun only the safe scope.

2. Intentionally broken example: blind side-effect retry

retry(3) {
  sh './create-synthetic-release.sh'
}

Suppose attempt 1 creates synthetic-target/release-42.done and then exits nonzero because the response path is simulated to fail. Attempt 2 tries to create the same release again. The retry wrapper did exactly what it was told; the design is wrong.

# Synthetic first-attempt evidence
created=release-42
simulated_response=lost
exit=1

# Target-side evidence
synthetic-target/release-42.done exists

3. Repair: preflight, deterministic operation ID, verify target

def releaseId = 'release-42'

stage('Preflight') {
  sh "./verify-target-accepts '${releaseId}'"
}

stage('Apply once') {
  sh "./apply-idempotent-synthetic-release '${releaseId}'"
}

stage('Verify target') {
  sh "./verify-synthetic-release '${releaseId}'"
}

The repair is not “never retry.” The read-only preflight and verification may have bounded retry if transient. The mutation uses a deterministic ID and target-state check so Jenkins can distinguish “already applied” from “not applied.”

4. Failure mode: catchError creates misleading green/continuation

catchError(buildResult: 'SUCCESS', stageResult: 'SUCCESS') {
  sh './critical-security-gate.sh'
}
sh './publish.sh'

This is structurally dangerous: a critical gate failure can be hidden and publication can continue. Build results cannot improve once worse, but explicitly keeping results successful when an error is caught can still make the stage look acceptable. Correct the policy: critical gate failure should abort, or at minimum remain failed and prevent the side-effect stage.

5. Failure mode: swallowing timeout or abort

catchError can catch Pipeline interruptions by default. If the intention is for timeout/manual abort to stop the flow, use catchInterruptions: false or explicit exception handling that rethrows interruption. Do not broadly catch every exception and continue.

catchError(
  buildResult: 'FAILURE',
  stageResult: 'FAILURE',
  catchInterruptions: false
) {
  timeout(time: 5, unit: 'MINUTES') {
    sh './bounded-required-check.sh'
  }
}

6. Failure mode: approval holds scarce executor

node('lab-linux') {
  input 'Approve?'
  sh './run-approved-step.sh'
}

While waiting, the node allocation can occupy an executor/workspace. Repair by persisting necessary evidence, leaving the node, waiting for input, then allocating an agent again for deterministic approved work.

7. Failure mode: unbounded polling

waitUntil {
  return sh(script: './is-ready.sh', returnStatus: true) == 0
}

Without a surrounding timeout, this can wait indefinitely. It may also call the target forever. Add a deadline and choose a recurrence appropriate for the service; for long waits, prefer event-driven integration.

8. Security-sensitive boundaries

• Do not expose API tokens or approval secrets in URLs/logs.
• Do not use broad administrator credentials just to make retry succeed.
• Do not disable CSRF, authorization, TLS, or Script Security to bypass a failed step.
• Do not run untrusted remediation code on the controller.
• Do not let a human approval alone prove that the external target is still in the same state as when approval was requested.

9. Performance symptoms and evidence

10. Repair without hiding the cause

Never delete failed evidence just because the repaired run succeeds. Keep the original build URL, exact revision, first exception, attempt count, and target state. Commit the repair as a new source revision, run the smallest safe scope, and link the before/after evidence.

Knowledge check

Official references and version notes

• Jenkins LTS changelog — current LTS and tested Java configurations.
• Pipeline: Basic Steps — current retry, timeout, catchError, waitUntil, sleep, and related step contracts.
• Pipeline: Input Step reference — input, submitter restrictions, identifiers, and captured approver identity.
• Pipeline: Basic Steps plugin — current plugin baseline and dependencies.
• Pipeline: Input Step plugin — current plugin baseline and security history.
• Jenkins Pipeline handbook — durable Pipeline execution and Jenkinsfile concepts.
• Pipeline Best Practices — controller/agent boundaries and safe Pipeline design.