Why can a Jenkins Pipeline script fail with java.io.NotSerializableException, and what does @NonCPS change about a method?

## A Jenkinsfile is not ordinary Groovy Jenkins Pipeline builds are **durable**: a build can wait days at an approval, and if the controller is restarted mid-run the build resumes where it stopped rather than starting over. No ordinary JVM thread can do that, because a thread's stack cannot be written to disk and reloaded. So the Pipeline engine does not run your script on a normal thread. It transforms it into **continuation-passing style (CPS)** — the program is rewritten so that its execution state is an explicit data structure the engine owns rather than a JVM stack. At every step boundary that state is serialized to the build's directory on disk. That is the whole trick, and every strange Groovy behaviour in a Jenkinsfile follows from it. ## Where the exception comes from The persisted state includes your local variables. Consider: ```groovy def version = null def matcher = readFile('build.gradle') =~ /version = '(.+)'/ if (matcher.find()) { version = matcher.group(1) } sh "echo ${version}" ``` `matcher` is a `java.util.regex.Matcher`, which is not serializable. It is still in scope when `sh` runs, so the engine tries to persist it and the build dies with `java.io.NotSerializableException: java.util.regex.Matcher`. The message names the type, which is the main clue you get. The usual offenders are the same handful: regex matchers, streams and readers, objects returned by ad-hoc XML or JSON parsing, and Jenkins model objects fetched through the API. ## The four ways out 1. **Drop the reference before the next step.** Extract what you need into a `String` and set the variable to `null`. Crude, but it works and the intent is visible. 2. **Convert to plain serializable data.** Strings, numbers, lists and maps of those all persist fine. 3. **Confine it to a `@NonCPS` method** — see below. This is the idiomatic fix, because the non-serializable object never escapes a frame that is never persisted. 4. **Use a step instead of raw Java.** Where a pipeline step exists for the job — reading properties, parsing files — it returns data the engine can already persist. ## What @NonCPS does ```groovy @NonCPS def extractVersion(String text) { def m = text =~ /version = '(.+)'/ return m.find() ? m.group(1) : null } node { def text = readFile 'build.gradle' def v = extractVersion(text) // Matcher never survives the call sh "echo ${v}" } ``` Annotating a method `@NonCPS` tells the engine to skip the CPS transform for it: the method executes as ordinary compiled Groovy on the calling thread. Its local variables live on a real JVM stack and are never serialized, so non-serializable objects inside it are harmless — as long as they do not leak out through the return value. The cost is that the method is now outside the durable execution model. It runs to completion in one go and cannot be suspended partway, and the documented restriction is that it must not call pipeline steps or other CPS-transformed methods. Treat `@NonCPS` as "pure computation only": take serializable inputs, do plain Groovy or Java work, return serializable output. ## The other CPS symptoms The same transform explains other oddities candidates half-know: - **Speed.** Every transformed method call goes through the interpreter, so a tight loop over ten thousand items is dramatically slower than plain Groovy. Heavy computation belongs in a `@NonCPS` method, in a script the pipeline shells out to, or outside the pipeline entirely. - **Closures.** Iteration idioms built on closures, such as `.each { }` and `.collect { }`, interact awkwardly with the transform; classic `for` loops are the safe, conventional choice in CPS-transformed pipeline code. - **Groovy features that do not survive the rewrite.** Some language constructs behave differently or not at all once transformed, which is why a snippet that runs fine in `groovysh` can misbehave in a Jenkinsfile. ## Why this matters in an interview The question separates people who have written Jenkinsfiles from people who have debugged them. The right shape of answer is causal, not incantatory: durability requires persisting state, persisting state requires serializable locals, `NotSerializableException` is that requirement being violated, and `@NonCPS` is the sanctioned way to keep a non-serializable object out of persisted state. Someone who has only heard "add `@NonCPS` when it complains" will not be able to say why the annotation must not call steps.