GitHub Actions "Matrix must define ..." - Fix Matrix Syntax Errors

The strategy.matrix block is malformed: it has no values, the include/exclude entries are the wrong shape, or a step references a matrix key that is not part of every combination.

What this error means

The workflow fails to compile with a matrix error, or jobs expand into unexpected combinations. An empty or mistyped matrix is rejected before any job starts.

Error: Matrix vector 'node' does not contain any values
# or
Error: The workflow is not valid. Matrix must define at least one vector

Common causes

Empty or non-list matrix dimension

Each matrix key must map to a non-empty list. A key set to null, an empty list, or a scalar produces "does not contain any values".

Malformed include or exclude

include and exclude must be lists of objects whose keys match matrix dimensions. A flat list or mismatched keys is rejected or silently adds unintended combinations.

Referencing a key absent from some combinations

If a matrix key only exists via include, combinations without it leave matrix.<key> empty, breaking steps that assume it is always set.

How to fix it

Define each dimension as a non-empty list

strategy:
  matrix:
    node: [18, 20, 22]
    os: [ubuntu-latest, macos-latest]
runs-on: ${{ matrix.os }}

Use include/exclude with matching keys

Add or remove specific combinations with objects whose keys align to the matrix dimensions.

strategy:
  matrix:
    node: [18, 20]
    os: [ubuntu-latest]
    include:
      - node: 22
        os: macos-latest
    exclude:
      - node: 18
        os: ubuntu-latest

How to prevent it

• Validate matrix shape with actionlint before pushing.
• Keep every dimension a non-empty list and align include/exclude keys.
• Add fail-fast: false during debugging so one bad combination does not cancel the rest.

Related guides