GitHub Actions "Unrecognized named-value: 'matrix'"

The matrix context only exists inside a job that declares strategy.matrix. Referencing \${{ matrix.x }} in a key evaluated before the matrix expands, or in a job with no matrix, fails validation.

What this error means

The workflow fails at parse time pointing at a \${{ matrix.* }} reference in a place the matrix context is not available, such as a non-matrix job or a top-level key.

Invalid workflow file: .github/workflows/ci.yml#L14
Unrecognized named-value: 'matrix'. Located at position 1 within expression: matrix.os

Common causes

Job has no strategy.matrix

matrix is only defined for jobs that declare a matrix; other jobs cannot reference it.

Referenced in a context evaluated too early

Some keys (like reusable-workflow uses) are resolved before the matrix context is in scope.

How to fix it

Declare the matrix and reference it in scope

1. Add strategy.matrix to the job that uses matrix.* values.
2. Move the matrix reference into runs-on, steps, name, or env of that same job.
3. If you need the value in a reusable workflow uses key, pass it as an input instead.

jobs:
  build:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - run: echo "Building on ${{ matrix.os }}"

How to prevent it

• Only reference matrix.* inside the job that owns the matrix.
• Pass matrix values into reusable workflows via with, not by referencing matrix in the uses key.

Related guides