Pipeline Steps, Error Handling, retry, timeout, catchError, input, waitUntil, and Resilient Flow Control: Concepts, Architecture, and Mental Model

1. Resilience is not “keep going at any cost”

Chapters 09–11 established how Jenkins persists Pipeline state, allocates agents, and executes Declarative or Scripted control flow. The next problem is what happens when work does not complete normally. Networks fail, agents disappear, services return temporary errors, operators abort a run, approvals take hours, and an external deployment may succeed even when Jenkins loses the response.

A resilient Pipeline does not convert every problem into a retry or a green build. It first classifies what happened, preserves the first failure, and decides whether another attempt is safe. A read-only status query is usually safe to repeat. Creating a release, charging a customer, rotating a key, publishing a package, or deploying a version may not be safe unless the operation has an idempotency key or independently verified target state.

2. Mental model: outcome → wrapper decision → durable state

Each Pipeline step produces a control-flow outcome. A normal return means success. An exception may mean command failure, timeout, manual abort, controller/agent interruption, or another plugin-specific failure. Wrappers such as retry, timeout, and catchError do not erase the underlying event; they decide what Pipeline should do next.

flowchart TD
 A[Step attempt] --> B{Outcome}
 B -->|success| C[Record success evidence]
 B -->|ordinary failure| D{Retry safe?}
 B -->|timeout / abort| E[Interrupted state]
 D -->|yes| F[Bounded retry]
 D -->|no| G[Preserve failure]
 F --> A
 E --> H{Policy preserves interruption?}
 H -->|yes| G
 H -->|explicitly handled| I[Record handled interruption]
 G --> J[Build/stage result]
 I --> J
 C --> J
 J --> K{External side effect?}
 K -->|none / verified idempotent| L[Continue if policy allows]
 K -->|uncertain| M[Verify target / compensate / stop]

3. The state you must track

4. retry: repeat a bounded body, not an unsafe transaction

The Basic Steps plugin retries its body when an exception occurs, up to the configured count. A user abort is not retried. Current Jenkins can also apply retry conditions for infrastructure-oriented cases such as agent loss.

retry(3) {
  sh './synthetic-read-only-check.sh'
}

This is appropriate when the script only observes synthetic state. It is not automatically appropriate around a deployment or publication. The wrapper cannot know whether an external system performed the action before the connection failed.

5. timeout: define a maximum wait boundary

timeout(time: 2, unit: 'MINUTES') {
  waitUntil(initialRecurrencePeriod: 1000) {
    return fileExists('synthetic-ready.flag')
  }
}

A timeout interrupts the nested body. The interruption is a first-class outcome, not just another false condition. Keep the boundary close to the wait you intend to bound so operators can tell what exceeded its budget.

6. catchError: continue while preserving a non-green result

catchError(
  buildResult: 'FAILURE',
  stageResult: 'FAILURE',
  catchInterruptions: false,
  message: 'Synthetic verification failed'
) {
  sh './verify-synthetic-output.sh'
}

catchError is useful when later evidence collection or cleanup must run even after a failure. It can set build and stage results separately. In this chapter we normally use catchInterruptions: false when an abort or timeout should remain an abort instead of being silently converted into an ordinary handled error.

7. input: human decision is durable Pipeline state

The Input Step pauses the Pipeline and can restrict who may proceed. An administrator can still respond, and users with appropriate cancellation permission may abort. If you need accountability, capture the approving submitter.

def approver = input(
  message: 'Proceed with the synthetic side effect?',
  ok: 'Proceed',
  submitter: 'lab-approver',
  submitterParameter: 'APPROVER'
)
echo "approved_by=${approver}"

Do not hold an agent solely while waiting for a person unless the workspace/executor truly must remain reserved. Prefer approval outside node, then allocate the agent for the approved work.

8. waitUntil: polling needs an outer stop condition

waitUntil repeats until its body returns true. Its recurrence period backs off, but there is no built-in maximum attempt count. An outer timeout prevents an infinite wait.

timeout(time: 90, unit: 'SECONDS') {
  waitUntil(initialRecurrencePeriod: 500, quiet: true) {
    return fileExists('synthetic-ready.flag')
  }
}

9. Safe recovery needs an idempotency story

For this course, irreversible behavior is simulated with a local marker keyed by an immutable operation ID. A repeated attempt first checks whether the marker already exists. Production systems should prefer native idempotency keys, immutable release IDs, deployment transaction IDs, or a target-state query rather than relying on a workspace file.

set -eu
mkdir -p synthetic-target
op_id="release-${BUILD_NUMBER}"
marker="synthetic-target/${op_id}.done"
if [ -f "$marker" ]; then
  printf 'already_applied=%s\n' "$op_id"
else
  printf 'applied_by_build=%s\n' "$BUILD_NUMBER" > "$marker"
fi

10. Inspect before changing control flow

• Record Jenkins core/Java and Pipeline plugin versions.
• Record job full name, build number/URL, cause, exact Jenkinsfile/source SHA, and current result.
• Capture the first failing console section before adding retry/catch logic.
• Record node/label/executor/workspace when an agent was involved.
• If an external side effect exists, verify target state independently before rerunning.

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.