GitHub Actions "nested matrix not supported" when defining a matrix inside a matrix

A strategy matrix accepts vectors of scalars, arrays, or objects - but a matrix value cannot itself be another matrix block. Attempting to nest one produces a validation error and the workflow refuses to run.

What this error means

The workflow fails to parse with an error indicating a nested or invalid matrix configuration when one matrix key contains another matrix.

Invalid workflow file: matrix values cannot contain a nested matrix.
The matrix must be a mapping of vectors to lists of scalar or object values.

Common causes

Treating matrix as recursive

A matrix is a single Cartesian product of its top-level vectors; it does not nest a second matrix inside a value.

Trying to vary sub-options per combination

Per-combination variation belongs in include entries with object values, not a nested matrix.

How to fix it

Flatten into top-level vectors

1. Express every dimension as its own matrix vector; the Cartesian product gives all combinations.
2. Use exclude to drop invalid pairings.

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

Use include for object-shaped combinations

1. Define each desired combination as an object under include.
2. Each include object becomes one job, letting you attach extra fields per leg.

How to prevent it

• Model multi-dimension builds as flat vectors plus include/exclude.
• Validate the workflow with actionlint before pushing.

Related guides