GitHub Actions "Job depends on unknown job" - needs: Errors

A needs: reference names a job that does not exist, or a downstream job did not run because the job it needs was skipped or failed and you did not handle that case.

What this error means

The workflow fails to compile with "depends on unknown job", or a job is silently skipped at runtime because a job listed in its needs was skipped or failed.

Invalid workflow file: .github/workflows/ci.yml
Job 'deploy' depends on unknown job 'biuld'.

Common causes

Misspelled or missing needs target

needs: must reference a job id defined in the same workflow. A typo or a job that was renamed/removed produces "unknown job".

Needed job was skipped or failed

By default a job is skipped if any job in its needs did not succeed. A conditionally skipped upstream job silently skips the downstream one.

How to fix it

Match needs to real job ids

Reference the exact job keys defined under jobs:. The id is the key, not the name:.

jobs:
  build:
    runs-on: ubuntu-latest
    steps: [{ run: make }]
  deploy:
    needs: build        # must equal the job key above
    runs-on: ubuntu-latest
    steps: [{ run: ./deploy.sh }]

Handle skipped or failed dependencies

1. Add if: always() (or success()/!cancelled()) when a job must run despite a skipped dependency.
2. Use needs.<job>.result in conditions to branch on the upstream outcome.
3. Read upstream outputs via needs.<job>.outputs.<name>.

How to prevent it

• Reference job ids (the keys), not display names, in needs.
• Decide explicitly with if: whether a job runs when a dependency is skipped.
• Validate the workflow with actionlint to catch unknown job references.

Related guides