GitHub Actions "Job 'x' depends on unknown job 'y'" in a Large Graph

By Daniel Zoghalchali·Latchkey

A needs: reference points at a job id that does not exist in this workflow. The target was renamed, deleted, or you expected a job from another file - needs only sees jobs in the same workflow.

What this error means

The workflow is invalid with "Job 'deploy' depends on unknown job 'package'", naming a job id that is not defined under jobs: in the same file.

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

Common causes

Renamed or removed job id

needs: must match a job key under jobs:. Renaming or deleting that job without updating every needs: leaves a dangling reference.

Expecting a job from another workflow

needs: cannot reference jobs in a different workflow file. Cross-workflow ordering needs workflow_run or a reusable workflow call, not needs:.

How to fix it

Reference an existing job id

Point needs: at a job key defined in the same file, and update all references when you rename a job.

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

Order across workflows correctly

1. Use on.workflow_run to chain a workflow after another finishes.
2. Or call a reusable workflow with uses: to compose graphs.
3. Validate with actionlint, which reports unknown needs targets.

How to prevent it

• Update every needs: when you rename or remove a job.
• Keep dependency graphs within one workflow, or use workflow_run/reusable workflows.
• Lint to catch dangling needs references before merge.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions