GitHub Actions "matrix cannot expand from secrets"

The strategy.matrix is evaluated before a job runs, in a context where the secrets context is not available. Referencing secrets there produces an invalid or empty matrix.

What this error means

A matrix referencing secrets.* fails validation or expands to nothing, so jobs do not run as expected.

Error: The workflow is not valid.
Unrecognized named-value: 'secrets'. matrix cannot expand from the secrets context.

Common causes

secrets referenced in matrix definition

matrix.include or a matrix vector references secrets.*, which is not resolvable at matrix-expansion time.

How to fix it

Build the matrix without secrets

1. Use static values, vars, or a fromJSON of a job output for the matrix.
2. Consume secrets inside the job steps (where the secrets context is available), not in the matrix.

strategy:
  matrix:
    target: ${{ fromJSON(needs.setup.outputs.targets) }}
steps:
  - run: deploy --token "${{ secrets.DEPLOY_TOKEN }}"

How to prevent it

• Keep secrets out of matrix definitions; reference them only inside steps.
• Generate dynamic matrices from a prior job output via fromJSON.

Related guides