Azure Pipelines Error: Complete Troubleshooting Guide

# Azure Pipelines Error: Complete Troubleshooting Guide

Azure Pipelines can fail for many reasons—agent problems, YAML syntax errors, service connection issues, or deployment failures. The error messages aren't always straightforward, especially when dealing with Azure DevOps' complex configuration options.

Let me walk through the most common Azure Pipelines errors and how to fix them systematically.

Understanding Azure Pipelines Logs

First, know where to find detailed error information:

1. 1.Go to Pipelines → [Your Pipeline] → [Failed Run]
2. 2.Click on the failed job
3. 3.Click on the failed step
4. 4.Look for red error icons and expand the output

Pro tip: Download the full log using the three-dot menu → "Download logs" for offline analysis.

Fix 1: YAML Syntax Errors

The most basic errors come from malformed YAML:

/pipelines/azure-pipelines.yml (Line: 12, Col: 1): A mapping was not expected

Common causes:

```yaml # WRONG - inconsistent indentation steps: - script: echo hello - script: echo world # Wrong indentation

# CORRECT steps: - script: echo hello - script: echo world ```

Diagnosis:

Use a YAML validator before committing:

```bash # Install yamllint pip install yamllint

# Validate your pipeline yamllint azure-pipelines.yml ```

Common fixes:

```yaml # Problem: Missing quotes around special characters - script: echo "Hello ${{ parameters.name }}" # WRONG

# Fix: - script: 'echo "Hello ${{ parameters.name }}"' # CORRECT

# Problem: Multiline string issues - script: | echo "Line 1" echo "Line 2" displayName: 'Multi-line script' # CORRECT indentation

# Problem: Condition syntax - script: echo "Deploy" condition: eq(variables['Build.SourceBranch'], 'refs/heads/main') # CORRECT ```

Fix 2: Agent Issues

Jobs stuck in queue or failing immediately.

Symptoms: - "Job is waiting for agent" - "No agent found that matches the specified demands" - "The agent request is taking a long time"

Solution A: Check agent availability:

1. 1.Go to Project Settings → Agent pools
2. 2.Check if agents are online
3. 3.Verify agent capabilities match your demands

Solution B: Specify correct agent:

```yaml pool: vmImage: 'ubuntu-latest' # Microsoft-hosted

# Or for self-hosted agents: pool: name: 'Default' # Your pool name demands: - agent.os -equals Linux - Docker ```

Solution C: Check agent capabilities:

```yaml # Add demands that your agent has pool: name: 'Default' demands: - npm - node.js

# Or check capabilities in a script: - script: | echo "Agent name: $(Agent.Name)" echo "Agent OS: $(Agent.OS)" echo "Agent version: $(Agent.Version)" ```

Fix 3: Variable and Parameter Errors

Variables not resolving correctly:

$(MyVariable) prints literally instead of its value

Cause: Variable syntax differences.

Solution:

```yaml # Runtime variables (macro syntax) - evaluated before execution - script: echo $(MyVariable)

# Template variables - compile time - script: echo ${{ variables.myVariable }}

# Runtime expression syntax - script: echo $[variables.myVariable]

# In conditions, use variables[] condition: eq(variables['Build.SourceBranch'], 'refs/heads/main') ```

For secret variables:

Secret variables can't be accessed in scripts directly:

```yaml # WRONG - secret variables don't get substituted in script - script: echo $(MySecret)

# CORRECT - map to environment variable - script: echo $MY_SECRET env: MY_SECRET: $(MySecret) ```

For parameters:

```yaml parameters: - name: environment type: string default: 'dev'

steps: - script: echo "Deploy to ${{ parameters.environment }}" ```

Fix 4: Service Connection Errors

Deployments fail with authentication errors:

Error: Subscription not found
Error: AADSTS700016: Application was not found

Diagnosis:

1. 1.Go to Project Settings → Service connections
2. 2.Check the connection status
3. 3.Click "Verify" to test the connection

Solution A: Recreate service connection:

1. 1.Go to Project Settings → Service connections → New service connection
2. 2.Choose the type (Azure Resource Manager, GitHub, etc.)
3. 3.Follow the authentication flow
4. 4.Grant permissions to pipelines

Solution B: Use workload identity (recommended for Azure):

# azure-pipelines.yml
- task: AzureWebApp@1
  inputs:
    azureSubscription: 'MyServiceConnection'  # Your service connection name
    appName: 'my-web-app'

For the service connection, use "Workload identity federation (automatic)" authentication method.

Solution C: Check subscription permissions:

# Add a step to verify access
- task: AzureCLI@2
  inputs:
    azureSubscription: 'MyServiceConnection'
    scriptType: 'bash'
    scriptLocation: 'inlineScript'
    inlineScript: |
      az account show
      az group list --output table

Fix 5: Build Artifact Issues

Problems publishing or downloading artifacts:

Error: Artifact name contains invalid characters
Error: No artifact found with name

Solution A: Publish artifacts correctly:

```yaml - task: PublishBuildArtifacts@1 inputs: pathToPublish: '$(Build.ArtifactStagingDirectory)' artifactName: 'drop' # No spaces or special characters publishLocation: 'Container'

# Or use the newer PublishPipelineArtifact - task: PublishPipelineArtifact@1 inputs: targetPath: '$(Build.ArtifactStagingDirectory)' artifact: 'drop' ```

Solution B: Download artifacts:

```yaml - task: DownloadBuildArtifacts@1 inputs: buildType: 'current' artifactName: 'drop' downloadPath: '$(System.ArtifactsDirectory)'

# Or newer DownloadPipelineArtifact - task: DownloadPipelineArtifact@2 inputs: artifact: 'drop' path: '$(System.ArtifactsDirectory)' ```

Solution C: Check file paths:

# Print directories for debugging
- script: |
    echo "Build sources: $(Build.SourcesDirectory)"
    echo "Build artifacts: $(Build.ArtifactStagingDirectory)"
    echo "System artifacts: $(System.ArtifactsDirectory)"
    ls -la $(Build.SourcesDirectory)

Fix 6: Deployment Failures

Deployments to Azure services fail.

Symptoms: - "Web app not found" - "Resource group not found" - "Insufficient permissions"

Solution A: Check resource exists:

```yaml - task: AzureCLI@2 inputs: azureSubscription: 'MyServiceConnection' scriptType: 'bash' scriptLocation: 'inlineScript' inlineScript: | # Check if resource group exists az group show --name myResourceGroup || echo "Resource group not found"

# Check if web app exists az webapp show --name myWebApp --resource-group myResourceGroup || echo "Web app not found" ```

Solution B: Use correct deployment task:

```yaml # For Azure Web Apps - task: AzureWebApp@1 inputs: azureSubscription: 'MyServiceConnection' appName: 'my-web-app' package: '$(Build.ArtifactStagingDirectory)/**/*.zip'

# For Azure Functions - task: AzureFunctionApp@1 inputs: azureSubscription: 'MyServiceConnection' appType: functionApp appName: 'my-function-app' package: '$(Build.ArtifactStagingDirectory)/**/*.zip'

# For Kubernetes - task: KubernetesManifest@1 inputs: action: 'deploy' kubernetesServiceConnection: 'myK8sConnection' namespace: 'default' manifests: | $(Build.SourcesDirectory)/k8s/deployment.yaml ```

Solution C: Add retry logic:

- task: AzureWebApp@1
  inputs:
    azureSubscription: 'MyServiceConnection'
    appName: 'my-web-app'
    package: '$(Build.ArtifactStagingDirectory)/**/*.zip'
  retryCountOnTaskFailure: 3  # Retry up to 3 times

Fix 7: Environment and Approval Issues

Deployments stuck waiting for approval:

Deployment to environment 'production' is waiting for approval

Solution A: Check environment settings:

1. 1.Go to Pipelines → Environments
2. 2.Click on the environment
3. 3.Check "Checks and approvals"
4. 4.Add/remove approvers

Solution B: Configure checks:

# In azure-pipelines.yml
stages:
- stage: Deploy
  jobs:
  - deployment: DeployWeb
    environment: 'production'  # This triggers checks
    strategy:
      runOnce:
        deploy:
          steps:
          - task: AzureWebApp@1

Solution C: Bypass for non-production:

stages:
- stage: DeployDev
  jobs:
  - deployment: DeployWeb
    environment: 'dev'  # No approvals for dev
    strategy:
      runOnce:
        deploy:
          steps:
          - task: AzureWebApp@1

Fix 8: Timeout Issues

Builds or deployments timeout:

The job running on agent ran longer than the maximum time of 60 minutes

Solution:

```yaml jobs: - job: LongRunningJob timeoutInMinutes: 120 # Increase to 2 hours steps: - script: ./long-build.sh

# For deployments - deployment: Deploy environment: 'production' timeoutInMinutes: 180 # 3 hours ```

Step-level timeout:

steps:
- script: ./slow-task.sh
  timeoutInMinutes: 30  # Step timeout

Fix 9: Container Job Errors

Running in containers fails:

Error: failed to register layer: Error processing tar file
Error: container 'build' not found

Solution:

jobs:
- job: ContainerJob
  container:
    image: mcr.microsoft.com/dotnet/sdk:7.0
    options: --user 0:0  # Run as root if needed
  steps:
  - script: dotnet build

For private registries:

```yaml resources: containers: - container: myprivate type: ACR azureSubscription: 'MyServiceConnection' resourceGroup: 'myResourceGroup' registry: 'myRegistry' repository: 'myImage' tag: 'latest'

jobs: - job: Build container: myprivate ```

Fix 10: Conditional Execution

Steps run when they shouldn't, or don't run when they should.

Solution:

```yaml # Run only on main branch - script: echo "Deploy to production" condition: eq(variables['Build.SourceBranch'], 'refs/heads/main')

# Run only on pull requests - script: echo "PR check" condition: eq(variables['Build.Reason'], 'PullRequest')

# Run only on tags - script: echo "Release" condition: startsWith(variables['Build.SourceBranch'], 'refs/tags/')

# Run on failure - script: echo "Something failed" condition: failed()

# Run always (even if previous steps fail) - script: echo "Cleanup" condition: always()

# Combine conditions - script: echo "Deploy" condition: and( eq(variables['Build.SourceBranch'], 'refs/heads/main'), succeeded() ) ```

Quick Reference: Azure Pipelines Errors

Debugging Commands

Add these to your pipeline for debugging:

```yaml steps: - script: | echo "=== Agent Information ===" echo "Name: $(Agent.Name)" echo "OS: $(Agent.OS)" echo "Version: $(Agent.Version)" echo "Build Directory: $(Build.SourcesDirectory)" echo "Artifact Directory: $(Build.ArtifactStagingDirectory)"

echo "=== Variables ===" env | sort

echo "=== File System ===" df -h ls -la $(Build.SourcesDirectory) displayName: 'Debug Info' ```