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

By Daniel Zoghalchali·Latchkey

A matrix needs at least one base axis (a key with a list of values). Providing only include/exclude, or an axis whose dynamic value expanded to an empty list, leaves no vector to expand.

What this error means

The run fails with "Invalid workflow file" and "Matrix ... must define at least one vector", or the matrixed job produces zero runs.

Invalid workflow file: .github/workflows/ci.yml
(Line: 9, Col: 7): Matrix must define at least one vector

Common causes

Only include/exclude, no base axis

A matrix with just include: and no list-valued key has no vector to start from.

A dynamic axis expanded to empty

An axis built from fromJSON(...) resolved to [], so there is nothing to combine.

How to fix it

Add a base axis with at least one value

1. Define a list-valued key under matrix.
2. Keep include/exclude as adjustments, not the only content.
3. Re-run the workflow.

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    include:
      - os: ubuntu-latest
        node: 20

Guard a dynamic matrix against empty

Default the generated axis to a non-empty list so it always has a vector.

echo "list=${list:-[\"ubuntu-latest\"]}" >> "$GITHUB_OUTPUT"

How to prevent it

• Always include at least one base axis in a matrix.
• Default dynamic axes to a non-empty list.
• Echo a generated matrix before consuming it.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions