GitHub Actions dynamic matrix from needs output empty, job skipped in CI

By Kaveh Alemi·Latchkey

When fromJSON(needs.<job>.outputs.matrix) resolves to [], GitHub creates zero matrix legs. The job neither errors nor runs; downstream steps that expected it to run are quietly skipped, which hides real gaps in coverage.

What this error means

The matrix job shows no legs and is marked skipped or successful with nothing executed. Tests you expected to run never ran, and jobs that needs this one may skip too.

# setup emitted an empty list, so the build matrix has no combinations
# jobs.build: skipped (0 matrix jobs)

Common causes

The generation logic produced an empty array

A filter (changed files, tags, labels) matched nothing, so the setup job emitted [] and the matrix expanded to no jobs.

A skipped or failed producer with a default empty output

When the producing job is skipped, its output defaults to empty, and fromJSON("[]") yields no combinations.

How to fix it

Detect an empty matrix and fail or fall back

1. In the setup job, check whether the generated list is empty.
2. Either provide a default combination or set a flag output.
3. Gate the matrix job on that flag so an empty run is explicit, not silent.

list=$(jq -c '.' out.json)
if [ "$list" = "[]" ]; then list='["ubuntu-latest"]'; fi
echo "list=$list" >> "$GITHUB_OUTPUT"

Guard the matrix job with an if condition

Only run the matrix job when the generated list is non-empty, so the skip is intentional and visible.

build:
  needs: setup
  if: needs.setup.outputs.list != '[]'
  strategy:
    matrix:
      os: ${{ fromJSON(needs.setup.outputs.list) }}

How to prevent it

• Treat an empty dynamic matrix as a deliberate, gated case.
• Emit a flag output alongside the list to branch on explicitly.
• Fail the build if an empty matrix would skip required checks.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions