GitHub Actions Dynamic Matrix from fromJSON Fails - Not an Array

A dynamic matrix fed by fromJSON of an upstream output fails because the output was empty, not valid JSON, or not shaped as an array the matrix expander accepts.

What this error means

The dependent job fails to expand its matrix, or produces zero jobs, when the JSON it consumes is empty or malformed. The producer job often succeeded, hiding the real cause.

Error: The template is not valid. .github/workflows/ci.yml:
matrix value 'fromJSON(needs.gen.outputs.list)' did not evaluate to an array

Common causes

Upstream output empty or truncated

If the producer job did not set the output (skipped step, wrong id, or size truncation), fromJSON receives an empty string and cannot produce an array.

JSON not an array of values

A matrix dimension needs a JSON array. A bare object, a quoted string, or trailing-comma JSON makes fromJSON fail or produce a non-array.

How to fix it

Emit valid JSON array as a job output

jobs:
  gen:
    runs-on: ubuntu-latest
    outputs:
      list: ${{ steps.set.outputs.list }}
    steps:
      - id: set
        run: echo 'list=["18","20","22"]' >> "$GITHUB_OUTPUT"
  test:
    needs: gen
    strategy:
      matrix:
        node: ${{ fromJSON(needs.gen.outputs.list) }}
    runs-on: ubuntu-latest

Validate the JSON before consuming it

1. Echo the producer output and confirm it is a non-empty JSON array.
2. Use a tool like jq -c to compact and validate the JSON you emit.
3. Guard the dependent job so it does not run on an empty list.

How to prevent it

• Always emit compact, valid JSON arrays for dynamic matrices.
• Map the producer step output to a job output and confirm it is non-empty.
• Validate the JSON shape (array of scalars or objects) before fromJSON.

Related guides