Bitbucket YAML Anchor "could not find expected" / Undefined Alias

By Daniel Zoghalchali·Latchkey

YAML anchors (&name) and aliases (*name) let you reuse a block. Referencing an alias before its anchor is defined, or in a file that never declares it, makes the parser fail.

What this error means

The file fails to parse with an undefined-alias error. The anchor is misspelled, defined after its use, or you tried to share an anchor across files (anchors are per-document only).

We couldn't parse your bitbucket-pipelines.yml file.
found undefined alias "build-step"
  in "bitbucket-pipelines.yml", line 18, column 11

Common causes

Alias used before the anchor is defined

YAML resolves top to bottom. A *build-step that appears before its &build-step anchor has nothing to point at.

Anchor name typo or cross-file reuse

A misspelled alias, or an anchor you expected to be available from another file, is undefined - anchors do not span documents.

How to fix it

Define the anchor before referencing it

Declare reusable blocks (commonly in definitions) above the steps that alias them.

definitions:
  steps:
    - step: &build-step
        name: Build
        script: [ npm run build ]
pipelines:
  default:
    - step: *build-step

Check anchor names and scope

1. Confirm the alias spelling matches the anchor exactly.
2. Move the anchor definition above its first use.
3. Keep anchors and aliases in the same file - they cannot cross documents.

How to prevent it

• Declare anchors near the top (e.g. under definitions) before any alias.
• Keep anchor/alias names identical and unique.
• Do not rely on anchors shared between files.

Frequently asked questions

Related guides

References

• GitHub Actions documentation