GitLab CI "parallel:matrix" needs Errors - Cross-Product Job Names

parallel:matrix expands one job into many - one per variable combination. A later job that needs a specific combination must reference it by its matrix variables, not the bare job name, or the reference fails.

What this error means

A downstream job’s needs (or dependencies) on a matrix job is rejected or pulls the wrong artifacts, because a matrix expands to many suffixed jobs and a plain name does not identify which one.

Pipeline Editor

This GitLab CI configuration is invalid:
'deploy' job needs 'build' job, but it was not found
# 'build' expanded into build: [aws], build: [gcp] - neither is named plain 'build'

Common causes

Matrix expands into suffixed jobs

A parallel:matrix job named build becomes build: [aws], build: [gcp], etc. There is no plain build job, so a bare needs: [build] may not resolve as intended.

needs does not specify the matrix variables

To depend on one combination, needs must include the matrix variables identifying it. Omitting them either fails or fans the dependency across all combinations.

How to fix it

Reference the exact matrix combination

Use the parallel:matrix form inside needs to point at one combination’s artifacts.

.gitlab-ci.yml

build:
  parallel:
    matrix:
      - PROVIDER: [aws, gcp]
  script: ./build.sh $PROVIDER
  artifacts: { paths: [dist/] }

deploy_aws:
  needs:
    - job: build
      parallel:
        matrix:
          - PROVIDER: [aws]
  script: ./deploy.sh aws

Or depend on the whole matrix

To consume every combination, needs: [build] pulls all expanded jobs and their artifacts.
To consume one, add the parallel:matrix selector with the identifying variables.
Validate in the Pipeline Editor’s "Needs" view to confirm the DAG resolves.

How to prevent it

Reference matrix combinations by their variables in needs, not the bare name.
Keep matrix variable sets small so the expanded names stay manageable.
Validate the DAG after adding cross-matrix dependencies.