Matrix job skipped - empty matrix combination

Symptoms

• Matrix strategy produces fewer jobs than expected
• Some OS/language combinations never run in the matrix
• Workflow completes green but certain matrix legs are absent from the run

GitHub Actions resolves exclude before include. An exclude that removes a key combination will also remove that combination from explicit includes.

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

• Matrix include/exclude block

  Copy
  cat .github/workflows/<file>.yml | grep -A30 'strategy:'

• Actual matrix jobs in the run

  Copy
  gh run view <RUN_ID> --repo <OWNER/REPO> --json jobs --jq '.jobs[] | .name'

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

Prevention

• After defining matrix include/exclude, manually verify the full cross-product with a dry-run.
• Use github.event.action == 'schedule' guards instead of complex exclude blocks.
• Add a post-job step that reports which matrix legs ran vs expected.
• Keep matrix dimensions small; split into separate workflows if the cross-product is large.