Azure Pipelines "Stage depends on unknown stage"

A stage-level dependsOn references a stage identifier the compiler cannot resolve. The name is misspelled, points at the stage displayName instead of the stage id, or the stages are listed in an order that hides the dependency.

What this error means

The pipeline fails to compile with Stage <name> depends on unknown stage <name>. The stage dependency graph cannot be built, so no stage starts.

/azure-pipelines.yml: Stage 'Deploy' depends on unknown stage 'biuld'.

Common causes

Misspelled or display-name reference

Stage dependsOn must use the stage: identifier, not the human-readable displayName. A typo or pointing at the label fails to resolve.

Implicit sequential order overridden

Stages run sequentially by default. Once you add any dependsOn, the implicit ordering is gone for that stage, so an omitted or wrong dependency breaks the graph.

How to fix it

Reference the exact stage identifier

Use the stage: name with matching case.

stages:
  - stage: Build
    jobs: [ { job: b, steps: [ { script: echo build } ] } ]
  - stage: Deploy
    dependsOn: Build        # the stage id, not the displayName
    jobs: [ { job: d, steps: [ { script: echo deploy } ] } ]

Fan-in with a list of dependencies

A stage can depend on several upstream stages - pass a YAML list.

stages:
  - stage: BuildLinux
  - stage: BuildWindows
  - stage: Release
    dependsOn:
      - BuildLinux
      - BuildWindows

How to prevent it

• Give stages short, unambiguous identifiers and reference those.
• When you add one dependsOn, declare every real dependency for that stage.
• Validate the pipeline so stage typos surface before a run.

Related guides