GitHub Actions nested matrix not supported in CI

By Daniel Zoghalchali·Latchkey

A job has exactly one strategy.matrix. You cannot nest a matrix inside a matrix. To get more dimensions, add more vectors to the same matrix (they cross-multiply) or split into separate jobs.

What this error means

A workflow that tries to define a matrix within a matrix fails validation, or the inner structure is treated as a plain value rather than a second matrix.

strategy:
  matrix:
    os: [ubuntu-latest]
    matrix:            # you cannot nest a matrix inside a matrix
      node: [18, 20]

Common causes

Trying to nest matrices for extra dimensions

Only one matrix per job is allowed. A nested matrix: key is invalid; extra dimensions belong as sibling vectors.

Confusing cross product with nesting

Multiple vectors already cross-multiply, which is what most nested-matrix attempts actually want.

How to fix it

Add vectors to a single matrix

1. Put every dimension as a top-level vector in one matrix.
2. They cross-multiply automatically into all combinations.
3. Use include/exclude to prune unwanted pairs.

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    node: [18, 20]   # 2 x 2 = 4 combinations

Split truly independent dimensions into jobs

If two axes should not multiply, define separate jobs each with its own matrix rather than nesting.

How to prevent it

• Use one matrix per job with multiple vectors, not nesting.
• Rely on the cross product for combinations.
• Separate independent axes into distinct jobs.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions