GitHub Actions "fromJSON ... Unable to parse" in CI
fromJSON expects a strictly valid JSON string. An empty value, single quotes instead of double quotes, or a trailing comma makes it fail with a parse error during expression evaluation.
What this error means
A job fails while evaluating an expression with "Unable to parse" and a JSON snippet, commonly when a dynamic matrix is built from a step output that was empty or malformed.
Error: Unable to parse '[ {os: ubuntu-latest, } ]':
Unexpected character encountered while parsing valueDiagnose 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
The JSON uses single quotes or unquoted keys
JSON requires double-quoted keys and string values; {os: x} or '[...]' is not valid JSON.
The source output was empty
A step that should emit JSON produced nothing, so fromJSON receives an empty string it cannot parse.
How to fix it
Emit strict JSON from the producing step
- Generate the value with a tool that writes valid JSON (e.g.
jq -c). - Write it to
$GITHUB_OUTPUTas a single line. - Reference it with
fromJSON(steps.x.outputs.y).
matrix=$(jq -cn '{os:["ubuntu-latest","windows-latest"]}')
echo "matrix=$matrix" >> "$GITHUB_OUTPUT"Guard against an empty output
Default to a valid empty JSON value so fromJSON never sees an empty string.
echo "matrix=${matrix:-[]}" >> "$GITHUB_OUTPUT"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
- Produce JSON with
jq -c, not by string concatenation. - Default to
[]or{}when the source can be empty. - Echo the output and validate it before using fromJSON.