GitHub Actions "Matrix must define at least one vector" in CI

By Daniel Zoghalchali·Latchkey

A strategy.matrix needs at least one vector (a named list of values) to expand. When the block is empty, contains only include/exclude, or every vector is empty, GitHub stops with "Matrix must define at least one vector".

What this error means

The job fails immediately with "Matrix must define at least one vector." No matrix leg is created and the workflow does not proceed.

Error: Matrix must define at least one vector

Common causes

The matrix has only include or exclude

include and exclude refine a base matrix, they do not create one on their own. With no base vector, there is nothing to expand.

Every vector expanded to an empty list

A vector built from an expression, for example os: ${{ fromJSON(needs.setup.outputs.list) }}, that yields [] leaves the matrix with no values.

How to fix it

Declare at least one non-empty base vector

1. Add a real vector next to any include/exclude block.
2. Confirm the vector has at least one value.
3. Only then use include to add or extend combinations.

strategy:
  matrix:
    os: [ubuntu-latest]
    include:
      - os: windows-latest
        shell: pwsh

Guard against an empty dynamic vector

If a vector comes from a previous job, ensure that job always emits a non-empty JSON array, or skip the matrix job when the list is empty.

# fall back to a default so the array is never empty
echo "list=[\"ubuntu-latest\"]" >> "$GITHUB_OUTPUT"

How to prevent it

• Always include a base vector, not just include/exclude.
• Validate dynamic matrix output is a non-empty JSON array before use.
• Add a fallback value so an empty generation never zeroes the matrix.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions