Jenkins "Stage skipped due to when conditional" in CI

This is not an error but a frequent surprise: a stage you expected to run shows Stage "X" skipped due to when conditional. The Declarative when {} for that stage evaluated to false, usually a branch, environment, or expression that did not match the actual build.

What this error means

The build succeeds but a key stage (deploy, release) never executes, and the log shows Stage "Deploy" skipped due to when conditional.

[Pipeline] stage
[Pipeline] { (Deploy)
Stage "Deploy" skipped due to when conditional
[Pipeline] }

Common causes

A branch / environment condition did not match

A when { branch 'main' } skips on any other branch; when { environment ... } skips when the variable differs from the expected value.

A custom expression returned false

A when { expression { ... } } whose Groovy evaluates to a falsy value (empty string, null, false) skips the stage silently.

How to fix it

Inspect and correct the when condition

1. Echo the values the when block tests (env.BRANCH_NAME, parameters) right before the stage.
2. Adjust the condition to match the real build context, or use beforeAgent true so an agent is not allocated for skipped stages.
3. For complex logic, replace expression with explicit conditions you can reason about.

stage('Deploy') {
  when { branch 'main'; beforeAgent true }
  steps { sh './deploy.sh' }
}

How to prevent it

• Log the inputs a when block evaluates so skips are explainable.
• Use beforeAgent true to avoid allocating agents for skipped stages.
• Test when expressions for the branches and parameters you expect.

Related guides