GitHub Actions "The workflow is not valid ... matrix" invalid in CI

By Daniel Zoghalchali·Latchkey

GitHub parsed the workflow before running anything and the strategy.matrix block does not match the expected schema. A matrix must be a mapping of vector names to sequences, plus optional include/exclude; anything else fails validation.

What this error means

The run never starts. The Actions UI shows "The workflow is not valid" with a path like .github/workflows/ci.yml (Line: N, Col: M): Unexpected value ... pointing at strategy.matrix.

The workflow is not valid. .github/workflows/ci.yml (Line: 12, Col: 9):
Unexpected value 'node' for jobs.build.strategy.matrix

Common causes

A matrix vector is a scalar, not a list

Writing node: 20 instead of node: [20] makes the value a scalar. Each matrix vector must be a sequence of values.

An unexpected key inside strategy.matrix

Only vector names plus the reserved include and exclude keys are allowed. A stray key (a typo, or max-parallel placed inside matrix) fails schema validation.

How to fix it

Make every vector a list and keep the shape correct

1. Read the Line/Col in the error and open that spot in the workflow.
2. Wrap scalar vector values in a list, for example node: [18, 20, 22].
3. Move max-parallel and fail-fast under strategy, not under matrix.

strategy:
  fail-fast: false
  max-parallel: 4
  matrix:
    node: [18, 20, 22]

Validate the file before pushing

Lint the workflow locally so schema errors surface before they reach the Actions parser.

# actionlint catches invalid strategy.matrix shapes
actionlint .github/workflows/ci.yml

How to prevent it

• Always express matrix vectors as YAML sequences, never scalars.
• Keep fail-fast and max-parallel as siblings of matrix, under strategy.
• Run actionlint in a pre-push hook or a lint job.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions