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.osDiagnose it: print the context before you change anything
Most workflow-expression bugs are not syntax errors, they are an expression reading something that is empty. GitHub resolves a missing property to an empty string instead of failing the run, so a wrong reference looks like a logic bug rather than a mistake. Dump the contexts first and you will usually see the answer immediately.
- name: Dump contexts
run: |
echo '--- github ---' ; echo '${{ toJSON(github) }}'
echo '--- needs ---' ; echo '${{ toJSON(needs) }}'
echo '--- steps ---' ; echo '${{ toJSON(steps) }}'
echo '--- matrix ---' ; echo '${{ toJSON(matrix) }}'
echo '--- inputs ---' ; echo '${{ toJSON(inputs) }}'Check the context is allowed where you used it
Contexts are not available everywhere. The same expression can be valid in a step if and invalid in a job if, which is why an expression that works in one workflow fails when moved.
| Where you wrote it | Contexts available there |
|---|---|
run-name | github, inputs, vars |
concurrency | github, inputs, vars |
Top-level env | github, secrets, inputs, vars |
jobs.<id>.if | github, needs, vars, inputs |
jobs.<id>.steps.if | github, needs, strategy, matrix, job, runner, env, vars, steps, inputs |
jobs.<id>.outputs | Full access, including secrets |
Reusable workflow outputs | github, jobs, vars, inputs |
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
- Add strategy.matrix to the job that uses matrix.* values.
- Move the matrix reference into runs-on, steps, name, or env of that same job.
- 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 }}"Catch it before it reaches CI
Every failure in this cluster is statically detectable. actionlint parses workflow expressions, checks context availability against the same rules above, and validates needs references, so these bugs never need to cost you a run.
# one-off
docker run --rm -v "$(pwd):/repo" --workdir /repo rhysd/actionlint:latest -color
# as a job, before anything expensive runs
- uses: actions/checkout@v4
- run: |
bash <(curl -s https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
./actionlint -colorHow 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.