Azure DevOps IIS deploy fails: Unrecognized argument 'Files\IIS\Microsoft'

TL;DR

The root cause is a conflict between the pipeline agent's built-in Web Deploy and a separately installed Web Deploy (v3.6/v4) on the target Windows server: msdeploy.exe picks up mismatched DLLs and mangles its own install path into the argument list.

Steps

1. Azure App Service / IIS Web App Deploy pipelines start failing with: Unrecognized argument 'Files\IIS\Microsoft'. All arguments must begin with "-". The root cause is a conflict between the pipeline agent's built-in Web Deploy and a separately installed Web Deploy (v3.6/v4) on the target Windows server: msdeploy.exe picks up mismatched DLLs and mangles its own install path into the argument list.
2. Uninstall Web Deploy from the target server (via Apps & Features) and let the pipeline agent use its own bundled version: multiple reporters confirmed deployments succeed after removing Web Deploy v3.6/v4 from the machine. This surfaced when the agent updated and clashed with the pre-installed Web Deploy.

When to use

You are seeing this: Azure App Service / IIS Web App Deploy pipelines start failing with: Unrecognized argument 'Files\IIS\Microsoft'. Use this skill when you run into "Azure DevOps IIS deploy fails: Unrecognized argument 'Files\IIS\Microsoft'".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

Versions mentioned in the source: v3.6. If you are on something much newer or older, the details may have shifted.

Why this happens

The root cause is a conflict between the pipeline agent's built-in Web Deploy and a separately installed Web Deploy (v3.6/v4) on the target Windows server: msdeploy.exe

Question from the thread: Azure App Service / IIS Web App Deploy pipelines start failing with: Unrecognized argument 'Files\IIS\Microsoft'. All arguments must begin with "-". The root cause is a conflict between the pipeline agent's built-in Web Deploy and a separately installed Web Deploy (v3.6/v4) on the target Windows server: msdeploy.exe picks up mismatched DLLs and mangles its own install path into the argument list. Verified answer: Uninstall Web Deploy from the target server (via Apps & Features) and let the pipeline agent use its own bundled version: multiple reporters confirmed deployments succeed after removing Web Deploy v3.6/v4 from the machine. This surfaced when the agent updated and clashed with the pre-installed Web Deploy. Full thread: https://vectle.com/threads/throvdWHErTtNDEPyZ2t-jsA