GitHub Actions "Unexpected value" in jobs.X.strategy.matrix in CI

By Kaveh Alemi·Latchkey

The workflow schema for strategy.matrix accepts named vectors plus the reserved include and exclude keys. Any other key, or a wrong nesting, produces "Unexpected value" at parse time and the run never starts.

What this error means

Validation fails with jobs.<id>.strategy.matrix Unexpected value '<key>' and a Line/Col pointing inside the matrix block.

The workflow is not valid. .github/workflows/ci.yml (Line: 14, Col: 7):
Unexpected value 'includes' for jobs.test.strategy.matrix

Common causes

A reserved key is misspelled

Writing includes or excludes (plural) instead of include/exclude is read as an unknown vector-like key and rejected.

A non-matrix key placed inside matrix

Keys like fail-fast or max-parallel belong under strategy, not matrix. Nesting them inside triggers "Unexpected value".

How to fix it

Use the exact reserved key names

1. Correct includes/excludes to the singular include/exclude.
2. Move fail-fast and max-parallel up under strategy.
3. Keep only vector names and include/exclude inside matrix.

strategy:
  fail-fast: false
  matrix:
    node: [18, 20]
    include:
      - node: 20
        os: macos-latest

Lint for schema errors

Run actionlint so unexpected matrix keys are caught before the push reaches GitHub.

actionlint

How to prevent it

• Use singular include/exclude, never the plural forms.
• Keep fail-fast and max-parallel under strategy, not matrix.
• Lint workflows to catch unexpected keys early.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions