Azure Pipelines YAML Schema "Unexpected value X"

By Kaveh Alemi·Latchkey

The YAML parsed fine, but a key appears where the pipeline schema does not expect it - a property misspelled, placed under the wrong parent, or indented one level off. The compiler rejects the unexpected value.

What this error means

The run fails with Unexpected value '<key>' at a line/column. The document is valid YAML; the structure violates the pipeline schema for that position.

azure-pipelines

/azure-pipelines.yml (Line: 9, Col: 5): Unexpected value 'step'

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.

azure-pipelines.yml

# 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

Property under the wrong parent

Keys are schema-scoped. A steps: entry written as step:, or a job-level key placed under pool:, lands where the schema does not allow it.

Misspelled or misindented key

A typo (scripts: for script:) or an indent that moves a key under a sibling it should not nest in triggers an unexpected-value error.

How to fix it

Place keys under the correct parent

Use the exact schema key and nest it where the schema expects.

azure-pipelines.yml

jobs:
  - job: build
    steps:
      - script: echo build   # 'steps:' is a list of step objects

Check the key against the schema

Compare the flagged key to the Azure Pipelines YAML schema for that context.
Fix spelling and move the key under its correct parent.
Re-validate so no other unexpected values remain.

How to prevent it

Reference the YAML schema when adding unfamiliar keys.
Keep indentation aligned so keys nest under the intended parent.
Validate the pipeline after structural edits.

Frequently asked questions

What causes Azure Pipelines YAML schema "Unexpected value X"?

There are 2 common causes: property under the wrong parent and misspelled or misindented key. Keys are schema-scoped.

How do I fix Azure Pipelines YAML schema "Unexpected value X"?

There are 2 fixes depending on which cause you have: place keys under the correct parent and check the key against the schema. Work through them in order, since the first is the most common.

What does Azure Pipelines YAML schema "Unexpected value X" actually mean?

The run fails with Unexpected value '<key>' at a line/column.

How do I stop Azure Pipelines YAML schema "Unexpected value X" happening again?

Reference the YAML schema when adding unfamiliar keys. The prevention section lists 3 changes that keep it from recurring.

References

GitHub Actions documentation