Azure DevOps Pipelines: Fix Setup & Config Errors
Why This Is Happening
You just pushed code, watched the pipeline screen, and... nothing. Or worse , the pipeline starts and immediately dies with a cryptic error that tells you absolutely nothing useful. I've seen this exact situation trip up developers at every skill level, from people setting up their very first Azure DevOps pipeline to senior engineers migrating a 200-job enterprise build system into YAML. The frustration is real, and Microsoft's error messages rarely point you to the actual cause.
Azure DevOps Pipelines is the CI/CD engine inside Azure DevOps. It's designed to automatically build, test, and deploy your code every time someone pushes a change , but that automatic part depends on a surprisingly large number of moving pieces all being configured correctly at the same time. Agents need to be available. Triggers need to match your branch patterns. Service connections need valid permissions. Your YAML needs to be syntactically clean. One of those things being off is enough to bring everything to a halt.
The most common category of failures I see breaks down into four buckets:
- Parallelism not granted, New Azure DevOps organizations don't automatically receive the free tier of parallel jobs. Your pipeline queues indefinitely and never starts.
- Trigger misconfiguration, A pipeline that was running fine stops triggering after a branch rename, a YAML path change, or a repository fork. The trigger definition no longer matches the actual branch or path.
- Agent pool problems, Either the Microsoft-hosted agent pool is temporarily unavailable, or a self-hosted agent has gone offline, or the pool permissions haven't been granted to the pipeline's project.
- YAML validation errors, A single indentation mistake, a missing colon, or a reference to an undefined variable group silently breaks the whole pipeline definition before it even reaches the queue.
What makes Azure DevOps Pipelines extra tricky to debug is that the error surfacing is inconsistent. Sometimes you get a red banner with an error code. Sometimes the pipeline just sits in "Queued" forever. Sometimes it starts, runs one step, and then fails with an exit code that maps to a totally different root cause than what you'd expect. The pipeline run logs are your best friend here, but you have to know where to look.
This guide covers every major failure mode I've encountered across personal projects, startup CI setups, and large enterprise Azure DevOps organizations. We'll start with the fix that resolves about 40% of new-user pipeline problems in under five minutes, and work through progressively more complex scenarios from there. Browse all Microsoft fix guides →
The Quick Fix, Try This First
If your Azure DevOps pipeline is sitting in "Queued" and never actually starts, the most likely culprit is that your organization hasn't been granted parallel job capacity. This catches nearly every new user off guard because the free tier isn't automatic anymore.
Here's what to check right now. Navigate to your Azure DevOps organization settings, that's the gear icon at the bottom-left of your screen, then Organization Settings, then Pipelines > Parallel jobs. Look at the "Microsoft-hosted" row for your project type (public or private). If both the purchased and free grant slots show zero, that's your problem.
For private projects, you need to request the free grant manually. Go to the Azure DevOps Parallelism Request form (search for it directly in your browser, Microsoft has it linked from the official Azure Pipelines pricing page). Fill it out with your organization name and intended use. Microsoft typically processes these within two to five business days. It feels slow, but it's a one-time step.
While you're waiting on the free grant, you have two ways to unblock yourself immediately:
- Switch to a self-hosted agent. Install the Azure Pipelines agent on your own Windows, Linux, or macOS machine. It's free and doesn't consume any parallel job quota. Go to Organization Settings > Agent pools > Add pool, create a self-hosted pool, then follow the agent download instructions. The whole setup takes about 15 minutes.
- Purchase a parallel job. Under Parallel jobs in Organization Settings, hit the Change button and add one paid parallel job. Paid jobs can run up to 360 minutes, six times the free tier's 60-minute limit, with no monthly cap.
If your pipeline does start but fails immediately, skip ahead to Step 2. But if it never leaves the queue, parallel job capacity is almost always the reason.
Before Azure DevOps Pipelines can do anything, it needs two things: an organization and a version control repository to watch. This sounds obvious, but I've seen pipelines fail silently because the repository connection was broken after a GitHub token expired or an Azure Repos permission was changed.
Start by confirming your organization exists and is active. Go to https://dev.azure.com/{yourorganization} directly in your browser. If you get a 404 or an access error, your organization URL may have changed or your account may not have access. Sign in at dev.azure.com and check the organization list on your profile page.
Next, open your pipeline definition and click Edit. Look at the top of the YAML file for the trigger section, and separately check the pipeline's Settings (three-dot menu > Settings) for the connected repository. If you're using GitHub, you'll see which GitHub App connection or OAuth token is being used. Click Authorize if it shows as expired or disconnected.
For Azure Repos, go to Project Settings > Repositories and confirm the repo is listed and your pipeline service account has at least Read access. A missing "Build Service" identity in the repo permissions is a classic silent failure.
# Test your repo connection from the pipeline by adding this temporary step:
steps:
- script: |
echo "Repository: $(Build.Repository.Name)"
echo "Branch: $(Build.SourceBranchName)"
echo "Commit: $(Build.SourceVersion)"
displayName: 'Debug - Print repo info'If this step runs and prints the expected values, your repository link is healthy. If it errors or prints empty values, the connection needs to be re-established through the pipeline's repository settings.
Triggers are the most common source of "my pipeline stopped running" complaints. Azure DevOps Pipelines supports several trigger types, CI triggers on code pushes, pull request triggers, scheduled triggers, and pipeline triggers that chain builds together. Each has its own YAML syntax and its own failure modes.
The first thing to check is whether your trigger block in the YAML matches the branch you're actually pushing to. Branch name matching is case-sensitive and supports glob patterns. A trigger written for main will not fire on Main or master.
# Correct trigger syntax, fires on pushes to main and any release/* branch
trigger:
branches:
include:
- main
- release/*
paths:
exclude:
- docs/**
- '*.md'If you have trigger: none at the top of your YAML, the pipeline is set to manual-only. This is sometimes added accidentally when cloning a template. Remove that line or replace it with the trigger block you actually want.
Pull request triggers use a separate pr key. If you want your pipeline to validate PRs into your main branch, you need both a trigger block for CI and a pr block for pull request validation, they are independent.
pr:
branches:
include:
- main
- developOne more thing that bites people constantly: if your pipeline YAML file lives in a subfolder of your repo rather than the root, you may need to specify the path to the YAML in the pipeline's settings (under Edit > ⋯ > Triggers). If Azure DevOps can't find the YAML at the expected path, it silently skips the run.
After fixing your trigger, test it by pushing a small change (add a blank line to a README) to the branch your trigger targets. Watch Pipelines > Runs for a new entry to appear within about 30 seconds.
When you see a pipeline that's stuck in "Queued" or fails with something like "No agent found in pool" or "All agents in the pool are disabled", the problem lives in your agent configuration. Agents are the compute resources that actually execute your pipeline jobs, they're defined in the YAML under the pool key.
For Microsoft-hosted agents, the pool names are specific strings. The most common ones are:
pool:
vmImage: 'ubuntu-latest' # Linux
vmImage: 'windows-latest' # Windows
vmImage: 'macos-latest' # macOSIf you mistype the vmImage value (for example, ubuntu-20.04 instead of ubuntu-latest, or a version string that Microsoft has retired), the pipeline will fail to find a matching agent. Check the current list of supported Microsoft-hosted agent images in the official Azure Pipelines documentation under "Microsoft-hosted agents", image availability changes as Microsoft adds and deprecates versions.
For self-hosted agents, go to Organization Settings > Agent pools and find your pool. Click into it and look at the Agents tab. You want to see your agent listed with a green dot showing Online. If it shows Offline, the agent service has stopped on the host machine. RDP or SSH into that machine and run:
# On Windows (in an elevated PowerShell prompt):
Get-Service -Name "vstsagent*"
Start-Service -Name "vstsagent.{orgname}.{poolname}.{agentname}"
# On Linux:
sudo systemctl status vsts.agent.{orgname}.{poolname}.{agentname}.service
sudo systemctl start vsts.agent.{orgname}.{poolname}.{agentname}.serviceAlso check that the agent pool has been granted access to your project. Under the pool's Security tab, your project should appear in the list with at least User permission. Missing project access is a common cause of "No agent found" errors in multi-project organizations.
YAML is notoriously unforgiving. A single space in the wrong place, a tab character where spaces are expected, or a missing colon after a key name will break the entire pipeline definition. Azure DevOps will show you a "YAML parse error" or "Unexpected value" message, but it doesn't always pinpoint the exact line, so you have to hunt.
The fastest way to validate your pipeline YAML before committing is to use the built-in validator. Open your pipeline, click Edit, and then click Validate in the top-right menu. This runs a server-side parse check and highlights any structural problems without actually running the pipeline.
Beyond syntax, task configuration errors are the next most common YAML issue. Every task in Azure Pipelines has a specific version, and the inputs it accepts change between versions. For example, DotNetCoreCLI@2 and DotNetCoreCLI@3 have different required inputs. If you copy a task snippet from an old guide and your organization is running a newer task version by default, you may hit errors about unrecognized or missing inputs.
# Always pin your task version explicitly:
- task: DotNetCoreCLI@2
inputs:
command: 'build'
projects: '**/*.csproj'
arguments: '--configuration $(BuildConfiguration)'Variable references are another landmine. A variable defined in a variable group must be linked to the pipeline before it can be referenced with $(variableName) syntax. If you see "Variable not set" or the variable expands to a literal string like $(mySecret) rather than its value, check Edit pipeline > Variables > Variable groups to confirm the group is linked. For secret variables, make sure you've checked the "Allow access to all pipelines" box or granted explicit access to your pipeline.
After fixing YAML issues, the run logs under Pipelines > Runs > [your run] > Job will show you each step's exit code. A step that exits with code 1 or higher has failed, click the step name to expand its full log output.
Once your pipeline builds successfully, the next challenge is deploying that build somewhere. Azure DevOps uses service connections to authenticate with external services, Azure subscriptions, Docker registries, Kubernetes clusters, GitHub, and anything else your pipeline pushes artifacts to. A broken or expired service connection is the #1 cause of deployment stage failures.
Go to Project Settings > Service connections to see all connections in your project. Each one shows a status indicator. If a connection shows a warning triangle or you see an error in your pipeline logs like "Could not find endpoint" or "TF401019: The Git repository with name or identifier X does not exist", the service connection is either missing, misconfigured, or lacks the right permissions on the target resource.
For Azure Resource Manager connections (the most common type for deployments to Azure), the connection uses either a service principal or workload identity federation. If your deployment started failing after a period of working fine, the most likely cause is the service principal's client secret expired. Open the connection, click Edit, and re-enter a fresh secret from the Azure Portal's App registrations page for the associated service principal.
# Reference a service connection in your deploy step like this:
- task: AzureWebApp@1
inputs:
azureSubscription: 'MyAzureServiceConnection' # Must match exact name in Project Settings
appType: 'webApp'
appName: 'my-app-name'
package: '$(Pipeline.Workspace)/drop/*.zip'The service connection name in your YAML must match the name in Project Settings exactly, including capitalization and spaces. One character difference means a "Could not find endpoint" failure at runtime.
For multi-stage pipelines that deploy to production environments, you also need to configure environment approvals. Under Pipelines > Environments, click your environment name and go to Approvals and checks. If an approval check is configured but no one has been added as an approver, your deployment stage will queue indefinitely waiting for a manual approval that can never come.
Advanced Troubleshooting
Once you've worked through the common fixes above and the pipeline still isn't behaving, it's time to get into the lower layers. These scenarios come up most often in enterprise environments, domain-joined machines running self-hosted agents, and complex multi-stage pipeline architectures.
Reading Pipeline Logs the Right Way
The Azure DevOps pipeline run log is far more detailed than most people realize. When a job fails, click into the failed step. At the top right of the log panel, click Download logs to get the full verbose output as a ZIP. Inside, each step has its own numbered log file. Look for lines starting with ##[error], these are the actual failure reasons, which are often buried 50+ lines below the red "failed" banner you see in the UI.
Enable System Diagnostics
When you queue a pipeline run manually (via Run pipeline button), there's an option called Enable system diagnostics. Check that box before running. This adds verbose agent-level logging that shows you exactly which agent was assigned, what capabilities it has, how long it sat in the queue, and what environment variables were set at job start. This is invaluable for diagnosing agent capability mismatch errors.
Agent Capability Demands
Self-hosted agents can have capability demands defined in your YAML. If your pool has three agents but only one has the capability your job demands, and that agent is busy, the job queues indefinitely even though agents are technically available. Check your YAML for demands: blocks and compare them against the capabilities listed in each agent's profile under Agent pools > [your pool] > [agent name] > Capabilities.
# Remove unnecessary demands that block scheduling:
pool:
name: 'MyPool'
demands:
- node.js # Only require this if your scripts actually need a specific Node versionFirewall and Network Issues for Self-Hosted Agents
Self-hosted agents on corporate networks or behind proxies need outbound HTTPS access to several Microsoft endpoints. The agent communicates with dev.azure.com on port 443, and also needs to reach Azure Blob Storage endpoints for artifact downloads. If your agent goes offline randomly or fails during artifact upload/download steps, check your firewall logs for blocked outbound connections to *.blob.core.windows.net and *.vsblob.visualstudio.com.
For proxy environments, configure the agent's proxy settings by editing the .proxy and .proxybypass files in the agent installation directory, or set the VSTS_HTTP_PROXY environment variable on the agent host machine before the agent service starts.
Pipeline Permissions and Project-Level Security
In larger organizations, the "Project Collection Build Service" and "[Project] Build Service" identities need specific permissions on repositories, environments, and service connections. If your pipeline suddenly loses access after an admin security review, these identities may have had permissions removed. Check under Project Settings > Repositories > [repo] > Security and ensure both build service identities have Read and Contribute to pull requests at minimum.
There are a handful of situations where you genuinely need Microsoft's intervention rather than configuration changes on your end: your parallelism request has been pending for more than 10 business days; your organization-level billing settings show parallel jobs purchased but the pipeline still reports zero capacity; or you're seeing intermittent agent allocation failures during peak hours that aren't explained by your capacity settings. In these cases, open a ticket through Microsoft Support with your organization name, the affected pipeline URL, and a screenshot of your Parallel Jobs settings page. That combination gets support engineers to the right team faster.
Prevention & Best Practices
Most Azure DevOps Pipelines headaches are preventable. The issues I see people fix once and then hit again two months later are almost always because they didn't put guardrails in place after the first incident. Here's how to stay ahead of them.
Pin your agent image versions deliberately. Using ubuntu-latest is convenient but means your pipeline automatically moves to whatever Microsoft designates as "latest." When Microsoft deprecates an old image and promotes a new one, breaking changes in the OS or pre-installed tooling can silently break your build. For production pipelines, pin to a specific version like ubuntu-22.04 and schedule intentional upgrades on your own timeline.
Store your pipeline YAML in a dedicated folder. Putting all your pipeline YAML files in a .azure-pipelines/ folder at the repo root makes it easy to use paths.exclude in triggers, so a change to a pipeline YAML for a different service doesn't accidentally trigger your service's pipeline. It also makes it obvious where to look during incidents.
Set explicit timeout values. The free tier caps individual jobs at 60 minutes. Paid jobs allow up to 360 minutes. Without explicit timeouts, a hanging test process or a stuck deployment can silently consume your entire monthly minute quota before you notice. Add a timeoutInMinutes value to every job that reflects a realistic upper bound, and set pipeline-level notifications to alert you when a run exceeds 80% of that threshold.
jobs:
- job: Build
timeoutInMinutes: 30 # Fail explicitly rather than silently consuming quota
cancelTimeoutInMinutes: 5Use templates for shared logic. If you have 10 microservices each with a pipeline that does the same build-test-push sequence, extract the common steps into a YAML template stored in a shared repository. One fix to the template propagates to all consuming pipelines automatically. Managing 10 identical pipeline files means 10 places where configuration drift can create inconsistencies that are painful to debug under pressure.
Monitor parallel job usage proactively. Set up a weekly reminder to check Organization Settings > Parallel jobs and look at the usage graph. If you regularly see jobs sitting in queue for more than five minutes, it's time to add capacity before it starts affecting your team's velocity, not after someone complains that deployments are taking an hour.
- Enable pipeline run notifications via Project Settings > Notifications so your whole team sees failures without checking the UI manually.
- Add a pipeline YAML validation step to your PR policy so broken YAML is caught before it merges to main and breaks the CI for everyone.
- Rotate service principal secrets on a calendar schedule (90 days recommended) and update service connections before the old secret expires, don't wait for a midnight deployment to fail.
- Document which agent pool each pipeline uses and why in a comment at the top of the YAML file, this saves huge amounts of time when onboarding new team members or responding to incidents.
Frequently Asked Questions
Why is my Azure DevOps pipeline stuck in "Queued" and never starts?
This is almost always a parallel job capacity problem, especially for new Azure DevOps organizations. Microsoft no longer automatically grants the free tier of parallel jobs to all new organizations, you have to request it via the Azure DevOps Parallelism Request form, and it can take several business days to be approved. In the meantime, install a self-hosted agent on any spare machine (your own laptop will do) and point the pipeline at your self-hosted pool. That bypasses the hosted parallelism quota entirely and gets your pipeline running while you wait for the grant.
My Azure DevOps pipeline was working fine and then stopped triggering. What changed?
The most common causes are a branch rename that no longer matches your trigger pattern, a push to a path that's now excluded in your YAML, or a service connection token that expired and broke the repository polling. Open the pipeline, click Edit, and carefully re-read the trigger: block, especially the branch includes and path excludes. Also check Project Settings > Service connections for any connections showing a warning state. If the pipeline YAML itself was recently edited by someone else, use the YAML diff in your repo history to see what changed.
What's the difference between Microsoft-hosted agents and self-hosted agents in Azure Pipelines?
Microsoft-hosted agents are fresh virtual machines provisioned by Microsoft for each pipeline job, you pick the OS image (Windows, Linux, or macOS) in your YAML, the job runs, and the machine is discarded. They're zero-maintenance but consume parallel job minutes from your quota and can't access resources inside private networks. Self-hosted agents are machines you manage yourself, they can be on-premises servers, cloud VMs, or even a developer laptop. They don't consume the hosted parallel job quota, can reach private network resources, and persist state between runs (which can be a pro or a con depending on your setup).
How do I fix "No hosted parallelism has been purchased or granted" in Azure DevOps?
This error means your organization has zero parallel job capacity on Microsoft-hosted agents. You have three paths forward: submit the free parallelism request form (search for "Azure DevOps Parallelism Request", allow several business days); purchase at least one paid parallel job through Organization Settings > Pipelines > Parallel jobs > Change; or configure a self-hosted agent pool as a free alternative while waiting. Public projects on Azure DevOps get a more generous free allocation automatically, so if your project is open source, setting project visibility to Public under Project Settings may resolve this immediately.
Can Azure Pipelines build and deploy apps written in Python, Node.js, and Java?
Yes, Azure Pipelines officially supports Node.js, Python, Java, PHP, Ruby, C#, C++, Go, Xcode, .NET, Android, and iOS. You can run builds for any of these languages in parallel across Linux, macOS, and Windows agents. Microsoft provides starter pipeline templates for most of these in the "New pipeline" wizard, which is the fastest way to get a working YAML baseline. From there, you extend with your specific test framework, packaging steps, and deployment targets.
How long can an Azure DevOps pipeline job run before it times out?
On the free tier with Microsoft-hosted agents, a single job can run for up to 60 minutes, with a total monthly cap of 1,800 minutes for private projects. Paid parallel jobs extend the per-job limit to 360 minutes with no monthly cap. Self-hosted agents have no time limit set by Microsoft, you can configure whatever timeout makes sense for your workload using the timeoutInMinutes setting in your job YAML. If you're running long integration test suites or large artifact compilations, a self-hosted agent or a paid job is the practical choice.