Azure Pipelines Parameter Type Mismatch / Unexpected Parameter

By Daniel Zoghalchali·Latchkey

A template was called with parameters that do not match its declaration - an unknown parameter name, a missing required one, or a value whose type is wrong. Azure validates template parameters strictly at compile time.

What this error means

The pipeline fails to compile with Unexpected parameter <name>, <name> is a required parameter, or a type error, pointing at the template: call or parameters: block. The template never expands.

/azure-pipelines.yml (Line: 5, Col: 7): Unexpected parameter 'buildConfig'
/templates/build.yml: A value for the 'vmImage' parameter is required.

Common causes

Unknown or misspelled parameter name

Passing a parameter the template does not declare (buildConfig vs buildConfiguration) is rejected - template parameter names are an exact contract.

Missing required parameter or wrong type

A parameter declared without a default is required; omitting it fails. Passing a string where a boolean or object is declared also fails type validation.

How to fix it

Match the template’s declared parameters

Pass exactly the names and types the template declares.

# template declares: parameters: [ {name: vmImage, type: string}, {name: runTests, type: boolean, default: true} ]
steps:
  - template: templates/build.yml
    parameters:
      vmImage: ubuntu-latest
      runTests: false

Declare types and defaults in the template

1. Give each parameter an explicit type so mismatches fail clearly.
2. Add a default to parameters that are optional; leave required ones without one.
3. Validate the calling pipeline after changing the template’s parameter contract.

How to prevent it

• Declare explicit type and sensible default for every template parameter.
• Keep parameter names stable; renaming is a breaking change for callers.
• Validate consumers when you change a shared template’s parameters.

Frequently asked questions

Related guides

References

• GitHub Actions documentation