GitLab CI "needs job exists but is not in an earlier stage"

By Kaveh Alemi·Latchkey

needs builds a DAG: a job can only need jobs that complete before it. If the needed job is in the same stage or a later one, GitLab rejects the dependency because the ordering is impossible.

What this error means

Validation fails saying the needed job exists but is not in an earlier stage, naming both jobs. The pipeline will not start until the stage ordering is fixed.

This GitLab CI configuration is invalid:
'deploy' job needs 'test' job, but 'test' is not defined in a prior stage

Common causes

Needed job is in the same stage

Two jobs in the same stage run in parallel, so one cannot need the other.

Needed job is in a later stage

A job cannot depend on something scheduled to run after it.

Stage order in stages: is wrong

The stages: list defines order; if the needed job stage is listed after the consumer stage, the DAG is invalid.

How to fix it

Move the needed job to an earlier stage

Ensure the dependency runs in a stage listed before the consumer stage.

stages: [build, test, deploy]

unit:
  stage: test
  script: make test

deploy:
  stage: deploy
  needs: [unit]
  script: make deploy

Reorder the stages list

1. Check the stages: array reflects the true ordering.
2. Confirm each needs target is in a stage before the consumer.
3. Re-validate in the Pipeline Editor.

How to prevent it

• Keep the stages list ordered to match your DAG.
• Only need jobs from strictly earlier stages.
• Use needs to parallelize, not to reorder same-stage jobs.

Frequently asked questions

Related guides

References

• GitHub Actions documentation