GitHub Actions "The job was canceled because a dependent job failed"

By Kaveh Alemi·Latchkey

When a job in a needs chain fails, dependents that have not started are canceled by default. The cancellation is a consequence of the upstream failure, not a fault in the canceled job.

What this error means

A downstream job shows as canceled with "The job was canceled because a dependent job failed", and its own logs are empty because it never started.

The job was canceled because "build" failed.

Common causes

Upstream needs job failed

A job listed in needs failed, so its dependents were canceled before running.

Required cleanup should still run

A cleanup/notify job got canceled because it did not opt into running on failure.

How to fix it

Fix the upstream job or allow downstream to run

1. Address the root cause in the failing needs job.
2. For jobs that must run regardless, add if: always() (or failure()).
3. Keep optional dependents off the critical needs chain.

notify:
  needs: [build, test]
  if: always()
  runs-on: ubuntu-latest
  steps: [{ run: ./notify.sh }]

How to prevent it

• Treat the canceled dependent as a signal to fix the upstream failure.
• Use if: always() for cleanup/notify jobs that must run.
• Keep non-essential jobs off the failing critical path.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions