Azure Pipelines "Stage depends on unknown stage"

By Kaveh Alemi·Latchkey

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'.

Diagnose it: variables, expressions, or the agent?

Azure Pipelines resolves compile-time expressions (${{ }}) before the run and runtime expressions ($[ ]) during it. Using the wrong one is the most common source of a value that is empty when you read it.

# print what the job actually resolved
- script: |
    echo "reason: $(Build.Reason)"
    echo "branch: $(Build.SourceBranch)"
    env | sort | head -40
  displayName: Dump context

# enable full diagnostics on a run: set system.debug = true as a variable

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.

Frequently asked questions

Related guides

References

• GitHub Actions documentation