GitLab CI "!reference" Tag Errors - Unknown or Invalid Reference

The !reference tag injects a value from another job or section by path. It fails when the path is wrong, points at a key that does not exist, or is used somewhere the value shape does not fit.

What this error means

Validation fails naming the bad reference - "unknown !reference" or a path that does not resolve. The rest of the file is fine; one !reference [job, key] does not point at a real location.

Pipeline Editor

This GitLab CI configuration is invalid:
jobs:test:script config contains unknown !reference value: [.setup, befor_script]

Common causes

Reference path does not exist

!reference [.setup, before_script] must point at an existing key. A typo in the job name or key (befor_script), or a section that was renamed, leaves the path unresolved.

Wrong nesting depth

The path is a list of keys from the top down. Missing or extra levels (e.g. referencing [job, script, 0] when script is a flat list at that job) fails to resolve.

Reference shape does not fit the target

Injecting a list reference where a scalar is expected, or a mapping where a list is expected, produces an invalid merged value.

How to fix it

Point the reference at a real path

Each element of the !reference list is a key, walked top to bottom to the value you want to reuse.

.gitlab-ci.yml

.setup:
  before_script:
    - apt-get update

test:
  before_script:
    - !reference [.setup, before_script]
  script:
    - make test

Match the value shape

Confirm the referenced key exists with exactly that name and dot-prefix.
Use the reference where the same value type fits (a list into a list, a scalar into a scalar).
Re-validate in the Pipeline Editor, which resolves !reference during the lint.

How to prevent it

Keep referenced templates dot-prefixed and stable; rename them deliberately.
Reference whole keys (before_script) rather than fragile index paths.
Validate after refactoring any section that other jobs !reference.