GitLab "job needs X, but X is not defined"

By Daniel Zoghalchali·Latchkey

needs: builds a DAG so jobs can start before their stage. Validation fails when a needed job does not exist or runs in a later (or same) stage than the job that needs it.

What this error means

Pipeline creation fails naming the broken dependency - a needs target that is undefined, or one that lives in a stage after the dependent job.

This GitLab CI configuration is invalid:
'deploy' job needs 'build' job, but 'build' is not defined in prior stages

Common causes

Referencing an undefined or misnamed job

A needs entry must match a real job name exactly. A typo or a job removed in a refactor leaves a dangling reference.

Needing a job in a later or same stage

By default a job can only need jobs from earlier stages. Pointing at a job in the same or a downstream stage is invalid unless same-stage needs are intended.

How to fix it

Reference a real job in an earlier stage

Confirm each needs target exists and runs before the dependent job.

stages: [build, test, deploy]

build: { stage: build, script: make build }
deploy:
  stage: deploy
  needs: ["build"]   # build is in an earlier stage

Keep needs names in sync on rename

1. When renaming a job, update every needs that points at it.
2. Order stages so dependencies always precede dependents.
3. Validate the DAG in the Pipeline Editor's "Needs" view.

How to prevent it

• Keep needs job names synchronized when renaming jobs.
• Order stages so dependencies always run first.
• Validate the DAG after any needs change.

Frequently asked questions

Related guides

References

• GitHub Actions documentation