Azure Pipelines "Encountered error(s) while parsing pipeline YAML"

By Kaveh Alemi·Latchkey

The compiler could not even parse the YAML into a document - it is a structural error (indentation, a tab character, an unclosed quote, or a key in the wrong place) that happens before any pipeline-specific validation.

What this error means

The run fails immediately with a parse error pointing at a line and column. Unlike a schema error (valid YAML, wrong shape), the document itself is malformed and cannot be loaded.

##[error]Encountered error(s) while parsing pipeline YAML:
/azure-pipelines.yml (Line: 12, Col: 7): While scanning a simple key,
could not find expected ':'.

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

Indentation or tab characters

YAML forbids tabs for indentation and is whitespace-sensitive. A stray tab or an inconsistent indent breaks the parse at that line.

Unclosed quote or missing colon

An unterminated string, a missing : after a key, or a misaligned list dash makes the scanner unable to build a valid mapping.

How to fix it

Fix indentation and remove tabs

Use consistent two-space indentation and convert any tabs to spaces.

jobs:
  - job: build
    steps:
      - script: echo "build"   # two-space indents, no tabs

Validate the document structure

1. Open the file in an editor that shows whitespace and reveals tabs.
2. Check the reported line/column for a missing colon or unclosed quote.
3. Run a YAML linter or the Azure DevOps validate action before pushing.

How to prevent it

• Configure the editor to insert spaces, never tabs, in YAML.
• Lint pipeline YAML locally before committing.
• Keep indentation consistent throughout the file.

Frequently asked questions

Related guides

References

• GitHub Actions documentation