GitHub Actions "matrix must define at least one vector"

By Daniel Zoghalchali·Latchkey

A matrix needs at least one keyed list of values (a vector) to expand into jobs. Declaring only include/exclude, or an empty matrix, gives nothing to expand and is rejected.

What this error means

The workflow fails to start with "matrix must define at least one vector", typically when the matrix has only an include array or an empty mapping.

Error: matrix must define at least one vector

Common causes

Only include/exclude, no base vector

The matrix provides include: rows but no base dimension list, so there is no vector to expand and augment.

Vector resolved to empty

A matrix key built from fromJSON resolved to an empty array, leaving no values to expand.

How to fix it

Provide at least one non-empty vector

1. Add a base dimension (e.g. os: [...] or node: [...]).
2. Ensure fromJSON-sourced vectors are non-empty arrays.
3. Use include only to augment an existing vector, not as the sole content.

strategy:
  matrix:
    node: [18, 20]
    include:
      - node: 20
        coverage: true

How to prevent it

• Always declare at least one keyed vector in a matrix.
• Validate fromJSON matrix sources are non-empty.
• Treat include/exclude as modifiers of a base vector.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions