GitHub Actions "Unrecognized named-value" - Fix Expression/Context Errors
An expression references a context or value that is not available where you used it. The most common case is using the secrets or env context in a place the workflow parser does not allow it.
What this error means
The workflow fails to compile with "Unrecognized named-value" or "Unexpected symbol", naming the context (such as secrets, env, or matrix) that is not valid in that position.
The workflow is not valid. .github/workflows/ci.yml (Line: 5, Col: 9):
Unrecognized named-value: 'secrets'. Located at position 1 within expression: secrets.TOKENDiagnose 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
Context not available in that scope
The secrets context cannot be used in a job-level if condition or in runs-on. The env context is not available in some keys, and matrix only exists inside a matrix job.
Malformed expression syntax
A missing brace in ${{ }}, an unquoted string, or mixing literal text with an expression without the correct delimiters produces an "Unexpected symbol" error.
How to fix it
Move the context to where it is allowed
Reference secrets inside a step env or with block, not in runs-on or a job-level conditional that the parser evaluates early.
steps:
- run: ./deploy.sh
env:
TOKEN: ${{ secrets.TOKEN }}Check expression delimiters and quoting
- Wrap every context reference in ${{ ... }} with matching braces.
- Quote string literals inside expressions with single quotes.
- Validate the file with actionlint, which parses expressions and flags invalid contexts.
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
- Consult the context availability table for each key before referencing a context.
- Run actionlint to validate expressions, not just YAML structure.
- Pass secrets through step env rather than embedding them in conditionals.