GitHub Actions "Unexpected value" at a specific workflow line
The YAML parsed but does not match the workflow schema. Actions found a value where it expected a known key or mapping.
What this error means
A validation annotation reads "The workflow is not valid. .github/workflows/x.yml (Line: N): Unexpected value <name>". The file is valid YAML but invalid as a workflow.
The workflow is not valid. .github/workflows/ci.yml (Line: 9): Unexpected value 'step'Diagnose 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
Misspelled schema key
Keys like steps, runs-on, and needs are exact. A typo such as step or run-on is not recognized.
A key at the wrong nesting level
Placing a step-level key under a job, or a job-level key under steps, produces an unexpected value.
How to fix it
Match keys to the workflow schema
- Compare each key against the documented workflow syntax.
- Fix spelling and nesting depth at the named line.
- Run actionlint to get the intended key suggestion.
actionlint .github/workflows/ci.ymlCatch 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
- Copy structure from a known-good workflow rather than from memory.
- Enable the Actions schema in your editor.