Jenkins / Editorial solution guide

Pipeline fails with java.io.NotSerializableException

Find the object retained across a persistence boundary and reduce it to explicit data.

About 3 min readContent reviewed

Read-only knowledge base · No public comments

Recognize the symptoms

A Pipeline performs a parsing or helper operation, then later fails with java.io.NotSerializableException near a suspending step. The line where the error appears may not be where the unsuitable object was created.

A library change or durability difference can make the problem appear inconsistent. A local Groovy or Python helper test may pass while Pipeline persistence still fails because its execution model and retained state differ.

Understand the likely causes

  • CPS-transformed Pipeline execution can retain local variables, closure captures, and referenced objects for persistence. A parser, iterator, stream, complex model object, or helper return value may remain reachable across a step boundary.
  • A NonCPS annotation can be misused around code that invokes Pipeline steps, creating a different call-direction problem. Lowering durability can reduce when persistence occurs and hide a symptom without making the retained state suitable.

Retain a bounded failure context

Capture run and revision, library identity, relevant plugin context, the exception class and concise stack excerpt, and the sequence from object creation to the next suspending step. Do not publish serialized program state, credentials, or a complete controller directory. A language-security rejection and a serialization exception are distinct observations; approving a method signature is not a general remedy for unsuitable saved data.

Trace what remains reachable

Inspect variables and closure captures around the failing boundary, including values returned by shared helpers. Ask which fields are actually needed afterward. A small count, list of identifiers, or plain result map may replace a large parser object. Avoid keeping an open resource merely because the helper has finished its immediate calculation. The diagnostic diagram below describes a data-design change, not a verified fix for a particular Java class.

text A retained-state review pattern 
complex parser result -> extract required plain fields
plain fields -> bounded Pipeline result record
release complex references before a suspending step

The diagram does not prove Java serializability or execute CPS. Actual object behavior, plugin steps, and library implementation require their own review and authorized validation.

Keep pure computation separate from Pipeline steps

Where appropriate, a small NonCPS helper can compute a plain return value without invoking asynchronous Pipeline steps. Do not move sh, sleep, input, or a whole orchestration stage into it to suppress the exception. Review documented CPS method mismatches for the exact call pattern. Test pure transformations with the language’s suitable local tools, while clearly separating that evidence from Pipeline integration and resumption behavior.

Repair state rather than reducing observability

Change the helper interface or variable lifetime so only needed suitable data crosses the persistence boundary. Keep the correction narrow and preserve the original failing scenario. Do not lower durability as the default fix, disable the sandbox, or approve unrelated methods. Those changes affect different contracts and can obscure the cause. If installed plugin behavior contributes, involve the platform owner and follow a bounded compatibility review rather than updating every component at once.

Verify the fix

A local pure-data test can verify extraction and expected values but cannot prove Jenkins persistence. In a separately authorized disposable Pipeline environment, verify the corrected minimal case across the relevant suspending boundary and any required restart scenario with matching plugin and library context. Record exactly what was exercised. This guide starts no controller, agent, job, restart, or administrative operation.

Keep it from recurring

  • Keep Pipeline orchestration state small, return plain bounded data from shared helpers, avoid long-lived parser and stream objects, and review closure captures. Treat CPS compatibility, language security, durability, and platform maintenance as separate review topics with explicit evidence.

Official references