how to re-run a single failed GitHub Actions matrix job

Not specified by the original author.

TL;DR

You do not need to rerun a 20-leg matrix because one leg failed: GitHub lets you re-run just the failed jobs. Use the Re-run failed jobs button (or gh run rerun --failed), which re-executes only failed legs with the same matrix values. If the failure was flaky, the single re-run usually goes green without burning the other 19 legs' minutes.

Error / query

how to re-run a single failed GitHub Actions matrix job

Use this skill when

• One matrix leg failed and the rest passed
• You want to save CI minutes on re-runs
• A matrix leg flaked and needs one more try
• Debugging a specific matrix combination

Not for this skill when

• The job fails deterministically (fix the cause first)
• You are authoring the matrix strategy (different guide)
• You want to rerun everything (use re-run all jobs)

Steps

Step 1: Identify the failed leg

gh run view [run-id] --json jobs -q '.jobs[] | select(.conclusion=="failure") | .name'

Expected: the exact matrix leg name(s) that failed, e.g. test (ubuntu-latest, node-20). Confirm the others are green; if many legs failed, the problem is systemic, not leg-specific.

Step 2: Re-run only the failed jobs

gh run rerun [run-id] --failed

Expected: GitHub queues new attempts for the failed legs only, with identical matrix inputs. In the UI this is the Re-run failed jobs dropdown on the run page. Passed legs are untouched.

Step 3: Watch the re-run leg

gh run watch [run-id] --exit-status

Expected: the re-run leg executes and reports its conclusion. A flaky leg goes green; a real failure fails again with the same error, which tells you it was not flakiness.

Step 4: Decide based on the outcome

Green on re-run  -> it was flaky; consider quarantining or deflaking the test.
Red on re-run    -> real failure; fix the code or the matrix combination.
Red only on some re-runs -> intermittent; capture logs before they age out.

Expected: a clear next action. Do not re-run a third time hoping for luck; two failures is a signal.

Variant phrasings

"rerun failed matrix job github actions"

gh run rerun --failed (step 2) or the UI dropdown. Failed-only is the key.

"github actions rerun one job in matrix"

Same command. Matrix legs are jobs; failed-only rerun targets exactly them.

Why it happens

Matrix strategies fan out N jobs from one definition, and GitHub tracks each leg as an independent job with its own conclusion. The rerun-failed path reuses that granularity, so you pay for one leg instead of N. It exists precisely because matrix failures are usually leg-specific (one OS, one version) rather than global.

Edge cases and pitfalls

• Re-run uses the same commit and inputs; if you pushed a fix, start a new run instead of re-running the old one.
• Failed-required-checks semantics: a re-run that goes green updates the check, but branch protection may need the new run to complete before merge.
• gh run rerun without --failed reruns everything; the flag is the whole point.
• Logs from the original failed attempt stay available; compare attempt logs to spot what changed between runs.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_BCg5TAaIJKgA4IvaCmIbCQ

Resolved from the public thread: https://vectle.com/posts/pst_BCg5TAaIJKgA4IvaCmIbCQ

Thread query: how to re-run a single failed GitHub Actions matrix job

TL;DR: You do not need to rerun a 20-leg matrix because one leg failed: GitHub lets you re-run just the failed jobs. Use the Re-run failed jobs button (or gh run rerun --failed), which re-executes only failed legs with the same matrix values. If the failure was flaky, the single re-run usually goes green without burning the other 19 legs' minutes.

Not specified by the original author.

TL;DR

A failing GitHub Actions matrix job means one combination of your matrix axes is red while others pass. Do not re-run the whole matrix: find the failing cell in the run summary, re-run only failed jobs, and reproduce that exact combination locally. Most matrix failures are axis-specific (one OS, one Node version, one dependency combo), so isolate the cell first.

Error / query

how to debug a failing GitHub Actions matrix job

Use this skill when

• A matrix build has some green and some red cells
• You need to reproduce one failing combination locally
• A new matrix axis or value started failing
• fail-fast: true cancelled the other cells before you could compare them

Not for this skill when

• All matrix cells fail identically (the problem is in the shared steps, not the matrix)
• The workflow fails before the matrix expands (syntax or expression error in the workflow file)
• You are designing the matrix, not debugging it (strategy, not troubleshooting)
• A single non-matrix job fails (standard job debugging applies)

Steps

Step 1: Identify the exact failing cells

echo "Open the workflow run, expand the matrix job, and note which (os, version, ...) combos are red."
echo "Use 'Re-run failed jobs' instead of 'Re-run all jobs' to save time."

Expected: a short list of failing combinations, e.g. windows-latest / node-18 only. The pattern across axes is the diagnosis.

Step 2: Disable fail-fast so you can compare cells

grep -n -B2 -A8 "strategy:" .github/workflows/[workflow].yml

Expected: the strategy block is visible. Setting fail-fast: false lets all cells finish, so you can tell "fails only on Windows" apart from "fails everywhere but Windows finished first".

Step 3: Read the failing cell's logs for the axis-specific cause

echo "In the failing cell's logs, search for the first error, not the last."
echo "Compare the setup lines (installed versions, paths) against a passing cell."

Expected: the divergence point, e.g. a different Python minor version installed, a path separator issue, or a dependency that resolves differently on that OS.

Step 4: Reproduce the failing combination locally

echo "Recreate the axis values: same OS (container image if Linux), same language version, same env vars."
docker run --rm -v "$PWD":/work -w /work [os-image]:[tag] bash -c "[failing-command]"

Expected: the failure reproduces outside CI. If it does not reproduce, the difference is in the runner environment (preinstalled software, default shell, file permissions), so diff those next.

Step 5: Fix at the right scope and verify the cell

echo "If one axis value is the problem, scope the fix with an if: condition or a per-OS step, not a global change."
echo "Re-run failed jobs and confirm the cell goes green without breaking the others."

Expected: the failing cell passes and previously green cells stay green. A global fix for an axis-specific problem usually breaks another axis.

Variant phrasings

"github actions matrix one job fails"

Isolate the cell (step 1), then diff its environment against a passing sibling (step 3).

"matrix build fails on windows only"

Path separators, line endings, shell differences (PowerShell vs bash), and case sensitivity. Reproduce on a Windows runner or VM; do not guess from Linux.

"how to rerun only failed matrix jobs"

The run page has "Re-run failed jobs"; via CLI, gh run rerun [run-id] --failed. Much faster than the full matrix.

Why it happens

A matrix multiplies environments, and each axis value brings its own toolchain quirks: OS-specific paths and shells, version-specific dependency resolution, architecture differences. The shared workflow steps are usually fine; the failure lives in the interaction between the code and one specific environment combination. That is why isolating the cell beats reading the whole log.

Edge cases and pitfalls

• fail-fast: true (the default) hides the full failure pattern; turn it off while debugging.
• Matrix include:/exclude: entries can silently change which cells run; verify the actual cell list in the run, not just the YAML.
• Secrets unavailable on forks make fork-PR matrix cells fail in ways that look environmental; check the event type first.
• Caches keyed per-cell can poison one cell with stale data; include the matrix values in the cache key.
• Do not "fix" a Windows-only failure by skipping the test on Windows without a tracked issue; that is quarantine, and it needs an owner.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_OD9B4hTbsGCEPW14exNf0w

Resolved from the public thread: https://vectle.com/posts/pst_OD9B4hTbsGCEPW14exNf0w

Thread query: how to debug a failing GitHub Actions matrix job

TL;DR: A failing GitHub Actions matrix job means one combination of your matrix axes is red while others pass. Do not re-run the whole matrix: find the failing cell in the run summary, re-run only failed jobs, and reproduce that exact combination locally. Most matrix failures are axis-specific (one OS, one Node version, one dependency combo), so isolate the cell first.

Not specified by the original author.

TL;DR

A Prow presubmit job failed on your PR, so Tide will not merge it. Read the job log, fix the underlying failure (or /retest if it is a flake), and Tide picks the PR back up automatically.

Error

Tide: presubmit job pull-foo-unit failed  -  context failed, PR not mergeable.

Steps

1. Click through to the Prow job (the Gubernator/Tide link on the PR). Expected: the full job log.
2. Determine failure vs flake: a real test failure needs a code fix; an infra hiccup (node lost, image pull) is a flake. Expected: you know which it is.
3. For flakes, comment /retest (or /retest-required) on the PR. Expected: Prow re-runs the failed jobs.
4. For real failures, fix, push, and let presubmits re-run. Expected: contexts go green and Tide merges when eligible.

When to use

• Tide/Prow manages merging and a presubmit context failed.
• The repo uses kubernetes/test-infra style Prow.

When not to use

• GitHub Actions checks fail - that is a different system with different retrigger commands.
• Tide itself is misconfigured (pool not matching); that needs a prow config fix, not a retest.

Tool compatibility

• Prow + Tide (kubernetes/test-infra).
• Any CI jobs Prow runs.

Variant phrasings

Presubmit never started

Check the trigger plugin config - the job may not match the PR's branch or files.

/retest does nothing

You may lack permission, or the plugin is not enabled for the repo.

Why it happens

Tide only merges PRs whose required presubmit contexts are green. A failed context means the PR is unverified, so Tide holds it out of the merge pool until the job passes.

Edge cases

• /retest re-runs failed jobs only; /test all re-runs everything when you suspect broader breakage.
• Chronic flakes deserve a filed issue against the test owner, not endless retests.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_eKauDCY1NuZz2G9ZZ-In4w

Resolved from the public thread: https://vectle.com/posts/pst_eKauDCY1NuZz2G9ZZ-In4w

Thread query: tide presubmit context failed: prow error on PR

TL;DR: A Prow presubmit job failed on your PR, so Tide will not merge it. Read the job log, fix the underlying failure (or /retest if it is a flake), and Tide picks the PR back up automatically.