GitLab CI "!reference" / extends Target Not Found

GitLab could not resolve a reuse mechanism - an extends base, a YAML anchor, or a !reference tag - because the target it names does not exist in the merged config.

What this error means

Validation fails naming the unresolved reference: an undefined extends base, an unknown anchor/alias, or a !reference path that does not exist after merging includes.

gitlab-ci

This GitLab CI configuration is invalid:
test job: undefined extension `.base_tset`
# or
!reference [".setup", "script"] could not be found

Common causes

Extends base or anchor not defined

The name in extends, or the anchor an alias points to, must exist exactly - including its dot prefix. A typo or a not-yet-included template fails.

!reference path points at nothing

A !reference [job, key] tag must name a real job and key in the resolved config. A wrong job name or a key the job lacks resolves to nothing.

How to fix it

Point extends and references at real targets

.gitlab-ci.yml

.base:
  image: node:20
  before_script: [npm ci]

.setup:
  script:
    - echo "setup"

test:
  extends: .base
  script:
    - !reference [.setup, script]
    - npm test

Ensure the target is defined before use

Confirm the extends base / anchor / referenced job exists, including its dot prefix.
When the target lives in an include, verify the include resolves first.
Re-validate against the merged YAML so reuse is checked end to end.

How to prevent it

Keep a flat reuse hierarchy: extend leaf templates, not other concrete jobs.
Define templates and anchors before the jobs that consume them.
Validate after refactoring shared templates and references.