GitHub Actions Matrix from a JSON File Produces No Jobs

A matrix generated from a JSON file or a prior job output expands into no jobs because the output was empty, not valid JSON, or fromJSON was applied to the wrong value.

What this error means

The downstream matrix job is skipped or expands to nothing, even though the generator step printed JSON. The fan-out you expected never happens.

# generator emitted nothing usable
matrix:
  include: ${{ fromJSON(needs.gen.outputs.targets) }}
# needs.gen.outputs.targets was '' -> no combinations

Common causes

Generator output was empty or not captured

The matrix job depends on an output written to GITHUB_OUTPUT. If the generator did not write it (or wrote to the wrong id), fromJSON receives an empty string and produces no jobs.

Invalid JSON shape

fromJSON needs a JSON array (or an object with include/exclude). A bare string, trailing comma, or single-quoted JSON fails to parse into matrix combinations.

How to fix it

Emit valid JSON to GITHUB_OUTPUT and depend on it

Have the generator write a compact JSON array to an output, then consume it with fromJSON in a job that needs it.

gen:
  runs-on: ubuntu-latest
  outputs:
    targets: ${{ steps.set.outputs.targets }}
  steps:
    - id: set
      run: echo "targets=$(jq -c . targets.json)" >> "$GITHUB_OUTPUT"
test:
  needs: gen
  strategy:
    matrix:
      target: ${{ fromJSON(needs.gen.outputs.targets) }}

Validate the JSON before it reaches the matrix

1. Run jq -e . on the file so a malformed JSON fails the generator step loudly.
2. Print the output value in a debug step to confirm it is a non-empty array.
3. Ensure the matrix job lists the generator under needs:.

How to prevent it

• Validate generated JSON with jq before emitting it.
• Use jq -c to produce compact single-line JSON for GITHUB_OUTPUT.
• Echo the matrix value in a debug step while developing dynamic fan-out.

Related guides