Azure Pipelines matrix "must be a mapping" strategy error

A strategy: matrix: block must be a mapping of named legs, each a mapping of variables. Writing it as a YAML list, or nesting it wrong, makes the schema reject it before any leg runs.

What this error means

Validation fails with matrix errors such as The value must be a mapping or Unexpected value, pointing at the strategy block.

Azure DevOps

/azure-pipelines.yml (Line: 8, Col: 7): A mapping was not expected
##[error]The matrix must be a mapping of leg names to variable mappings.

Common causes

matrix written as a list

Using - list items under matrix: is invalid; each leg must be a named key, not a sequence entry.

Variables not nested under each leg

A leg name with its variables at the wrong indentation breaks the mapping-of-mappings shape the schema requires.

How to fix it

Write matrix as named legs of variables

Each top-level key under matrix: is a leg name; under it, list the variables for that leg as key/value pairs.

azure-pipelines.yml

strategy:
  matrix:
    linux_py311:
      imageName: 'ubuntu-latest'
      pythonVersion: '3.11'
    windows_py312:
      imageName: 'windows-latest'
      pythonVersion: '3.12'
jobs: []

Reference the matrix variables correctly

Consume each leg variable with macro syntax in the job, like $(imageName), so legs differ as intended.

How to prevent it

Keep matrix: a mapping of leg names, never a list.
Nest each leg variable under its leg with consistent indentation.
Validate matrix changes with the pipeline editor before pushing.