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

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.

GitHub Actions

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

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

.github/workflows/ci.yml

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.

bash

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.