GitHub Actions "needs job X but it is not defined"

By Daniel Zoghalchali·Latchkey

A job lists a dependency under needs: that does not match any job id in the workflow. Actions cannot build the graph.

What this error means

The workflow is rejected with a message that a job needs another job that is not defined, naming the missing id.

The workflow is not valid. .github/workflows/ci.yml (Line: 20): Job 'deploy' depends on unknown job 'biuld'

Common causes

Typo in the needs reference

needs: biuld does not match the job id build.

Referencing a job in another workflow

needs: only works between jobs in the same workflow file.

How to fix it

Match needs to an existing job id

1. Correct the spelling to the exact job id.
2. Only reference jobs defined in the same workflow.

jobs:
  build:
    runs-on: ubuntu-latest
    steps: [{ run: make }]
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps: [{ run: ./deploy }]

How to prevent it

• Keep job ids short and consistent to reduce typos.
• Run actionlint, which validates the needs graph.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions