GitLab CI "needs: job ... is not defined" in CI

By Kaveh Alemi·Latchkey

A job's needs: lists a job name that GitLab cannot find in the pipeline, or that runs in the same or a later stage. needs can only point at jobs that exist and run earlier in the DAG.

What this error means

CI Lint or the pipeline fails with "needs config can only reference other jobs" or "X job needs Y, which is not defined". The dependent job never starts.

This GitLab CI configuration is invalid: jobs:deploy:needs:need 'build-app' is not defined in prior stages

Common causes

A typo or renamed job in needs

The needs entry does not match an actual job name, so GitLab cannot wire the dependency.

The needed job is not in an earlier stage

needs requires the referenced job to run before this one; pointing at a same-stage or later job is rejected.

How to fix it

Match the exact job name and order

1. Confirm the job named in needs exists with the exact same name.
2. Ensure that job runs in an earlier stage than the dependent job.
3. Re-run CI Lint to confirm the DAG resolves.

build-app:
  stage: build
  script: make

deploy:
  stage: deploy
  needs: ["build-app"]
  script: ./deploy.sh

Reorder stages so the dependency is earlier

Adjust the stages list (or the jobs' stages) so every needed job runs before the job that needs it.

stages:
  - build
  - deploy

How to prevent it

• Keep needs names in sync with job names after renames.
• Order stages so needed jobs always run earlier.
• Validate the DAG in CI Lint after editing dependencies.

Frequently asked questions

Related guides

References

• GitHub Actions documentation