Jenkins matrix Directive Failure - Fix Failing Cells & Excludes

By Kaveh Alemi·Latchkey

A declarative matrix expands the axes into one cell per combination. If any single cell fails - or a combination targets a label with no agent - the whole matrix is marked failed, even though most cells may have passed.

What this error means

A matrix stage fails and the stage view shows one or more red cells (e.g. os=windows, jdk=21) among green ones. Either that cell ran a step that failed, or an invalid combination could never be scheduled.

Jenkins console

[Matrix - OS = 'windows', JDK = '21'] script returned exit code 1
# or an unschedulable combination:
[Matrix - OS = 'aix', JDK = '8'] (pending) Waiting for next available executor

Common causes

A specific axis combination genuinely fails

The build or tests fail only for one cell (e.g. a JDK/OS pair), so that cell is red while the rest pass - a real, combination-specific bug.

An invalid combination was not excluded

The matrix generated a cell that makes no sense (an OS/version pair you do not support) and it has no agent or fails immediately, because no excludes {} removed it.

How to fix it

Exclude unsupported combinations

Use excludes {} so the matrix never generates cells you do not support or have no agent for.

Jenkinsfile

matrix {
  axes {
    axis { name 'OS';  values 'linux', 'windows' }
    axis { name 'JDK'; values '17', '21' }
  }
  excludes {
    exclude { axis { name 'OS'; values 'windows' }
              axis { name 'JDK'; values '17' } }
  }
  stages { stage('Test') { steps { sh 'make test' } } }
}

Fix the failing cell and match agents

Read the stage view to find which axis combination is red.
Reproduce that exact combination locally and fix the combination-specific failure.
Ensure each generated cell’s agent/label resolves to a real online node.

How to prevent it

Declare excludes {} for any axis combinations you do not support.
Confirm every generated cell maps to an available agent label.
Keep axis value lists minimal so the matrix stays small and debuggable.

Frequently asked questions

What causes "matrix cell failure"?