How would you design a pipeline template that fails fast with a clear error when a required tool is missing on the agent, instead of a raw "command not found"?

Add an explicit preflight step at the very start of the pipeline that checks for every tool the pipeline actually depends on (command -v <tool> or the platform equivalent for each one) and fails immediately with a clear message naming exactly which tool is missing and how to fix it, rather than letting the pipeline proceed and fail confusingly, deep in an unrelated build step, minutes later.

The core problem with a raw "command not found" failing deep in a build step is that it gives no context about why — someone debugging it has to work backward from an obscure shell error to "oh, this tool was never installed on this agent," which is a much harder diagnosis than it needs to be, especially for someone unfamiliar with exactly what that pipeline stage depends on.

The fix is a dedicated preflight/validation step, run first, before any real work begins, that explicitly checks for every tool the pipeline needs:

steps:
  - script: |
      set -e
      for tool in terraform kubectl jq; do
        if ! command -v "$tool" >/dev/null 2>&1; then
          echo "##vso[task.logissue type=error]Required tool '$tool' not found on this agent. Install it via the agent's provisioning script or use a Microsoft-hosted agent that includes it."
          exit 1
        fi
      done
    displayName: 'Preflight: verify required tools'

This turns an obscure mid-build failure into an immediate, named, actionable one — the pipeline fails in seconds, at the very first step, with a message that says exactly which tool is missing and points toward the fix, rather than a generic shell error surfacing wherever the tool happened to first be invoked.

Beyond the preflight step itself, a few complementary practices reinforce this: documenting the pipeline's tool dependencies explicitly (as a comment or a checked list at the top of the pipeline file) makes the preflight check self-documenting rather than a mysterious list that needs to be reverse-engineered from the check itself; and centralizing this preflight logic into a reusable pipeline template (Azure Pipelines supports template reuse) means every pipeline that shares the same tool dependencies gets the same fast, clear failure behavior without duplicating the check in every pipeline file.

• A preflight step checking for every required tool at the very start of the pipeline turns an obscure mid-build failure into an immediate, clearly-named one.
• ##vso[task.logissue type=error] gives Azure Pipelines a properly-formatted error annotation, making the failure visible and clear in the pipeline UI, not just buried in raw log text.
• Documenting tool dependencies alongside the preflight check keeps them from becoming a mystery list to reverse-engineer later.
• Centralizing the preflight logic into a reusable template avoids duplicating (and inconsistently maintaining) the same check across many pipeline files.

• Azure Pipelines: Logging commands
• Azure Pipelines: Template reuse