GitLab CI "extends" Errors - Unknown or Circular Base Job

By Kaveh Alemi·Latchkey

extends merges a base job into yours. It fails when the base does not exist, when extends points at something invalid, or when two jobs extend each other in a cycle.

What this error means

Validation fails naming an extends problem - an unknown base job, an invalid extends target, or "circular dependency detected" when bases reference one another.

This GitLab CI configuration is invalid:
test job: undefined extension `.base_tset`

Common causes

Base job not defined

The name in extends must match an existing job or hidden template exactly - including its dot prefix. A typo or a not-yet-included template fails.

Circular extends

If job A extends B and B extends A (directly or through a chain), GitLab cannot resolve the merge and reports a circular dependency.

How to fix it

Point extends at a real template

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

test:
  extends: .base
  script: npm test

Break the cycle

1. Map out which job extends which; find the loop.
2. Extract the truly-shared keys into a single leaf template both can extend.
3. Ensure templates are defined (or included) before the jobs that extend them.

How to prevent it

• Keep a flat hierarchy: jobs extend leaf templates, not other concrete jobs.
• Name templates with a clear dot-prefix convention.
• Validate after refactoring shared templates in the Pipeline Editor.

Frequently asked questions

Related guides

References

• GitHub Actions documentation