Skip to content

Troubleshooting

Jump to bottom
Michael Zanatta edited this page Aug 13, 2026 · 1 revision

Troubleshooting Guide

This guide provides solutions to common issues encountered when using AzureDevOpsDscNative.

Table of Contents

  1. Authentication Issues
  2. Resource Creation Issues
  3. Permission Issues
  4. Configuration Issues
  5. Performance Issues
  6. General DSC Issues

Authentication Issues

Issue: "Authentication Failed"

Symptoms:

  • Error: Unable to authenticate with Azure DevOps
  • Resource creation fails at authentication step
  • Tests fail with authentication error

Common Causes:

  • Incorrect credentials or token
  • Expired token or credentials
  • Insufficient permissions
  • Wrong organization name

Solutions:

  1. Verify credentials:

    # Test PAT connectivity
$pat = 'your-pat-token'
$headers = @{
    Authorization = 'Basic ' + [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":$pat"))
}
$response = Invoke-RestMethod -Uri 'https://dev.azure.com/YourOrg/_apis/projects' -Headers $headers
Write-Host $response.value.Count "projects found"

  2. Check token expiration:

    # Check when PAT expires in Azure DevOps portal
# Create new token if expired

  3. Verify permissions:

    • User should be in appropriate groups
    • PAT should have required scopes
    • For service principals, check role assignments

  4. Confirm organization name:

    # Use exact organization name from URL
# https://dev.azure.com/YourOrgName

Issue: "Insufficient Permissions"

Symptoms:

  • Error: Access denied or Insufficient permissions
  • Some operations succeed, others fail
  • Different errors for different resources

Solutions:

  1. Check group membership:

    # Verify user is in Project Collection Administrators for org-level operations
# Verify user is in Project Administrators for project-level operations

  2. Verify PAT scopes:

    # Scopes needed (in order of commonality):
# - Project & Team
# - Build
# - Packaging
# - Release
# - Service Connections
# - User Profile

  3. Check service principal:

    # For service principals:
# 1. Add to appropriate groups in Azure DevOps
# 2. Assign Azure RBAC roles if using Managed Identity
# 3. Verify certificate is properly configured

  4. Review audit logs:

    # Check Azure DevOps audit logs for denied operations
# Review Azure activity logs for ARM operations

Issue: "Token Expired"

Symptoms:

  • Worked previously, now fails
  • Error appears after extended use
  • Intermittent failures

Solutions:

  1. Create new PAT:

    • Go to Azure DevOps > User Settings > Personal access tokens
    • Create new token with same scopes
    • Update configuration with new token

  2. Check token expiration:

    # Check PAT expiration date when creating
# Default: 1 year, can extend to custom date

  3. Implement token rotation:

    • Create new token before expiration
    • Update configuration gradually
    • Monitor for authentication failures

Resource Creation Issues

Issue: "Resource Not Found"

Symptoms:

  • Error: Resource does not exist or Not found
  • Get method returns null
  • Test method returns false

Common Causes:

  • Resource hasn't been created yet
  • Typo in resource name
  • Resource is in different project or scope
  • Resource was deleted

Solutions:

  1. Verify resource exists:

    # Use Azure DevOps UI to confirm resource exists
# Check correct project/organization

  2. Check naming:

    # Names are case-insensitive for matching
# But case-sensitive for display
# Verify exact spelling

  3. Ensure dependencies are created first:

    # Check DependsOn includes required resources
DependsOn = '[AzDoProject]MyProject'

  4. Verify resource type:

    # Confirm using correct resource name
# AzDoProject (not AzDoProjects)
# AzDoTeam (not AzDoTeams)

Issue: "Resource Already Exists"

Symptoms:

  • Error: Resource already exists
  • Cannot create resource with same name
  • Name conflicts with existing resource

Solutions:

  1. Use unique name:

    # Add suffix or prefix to make unique
ProjectName = 'MyProject-v2'

  2. Update existing resource:

    # Instead of creating new, update existing
Ensure = 'Present'  # Will update if exists

  3. Remove existing resource first:

    # Create removal configuration
AzDoProject 'RemoveOld' {
    Ensure = 'Absent'
    ProjectName = 'OldName'
}

Issue: "Cannot Create Resource Due to Constraints"

Symptoms:

  • Error: Invalid property value
  • Error: Constraint violation
  • Error: Cannot modify immutable property

Solutions:

  1. Check immutable properties:

    # Cannot change after creation:
# - SourceControlType (Git vs Tfvc)
# - ProcessTemplate (Agile, Scrum, etc.)
# - Repository name (some cases)
# Must delete and recreate if needed

  2. Verify property values:

    # Check valid values
ProcessTemplate = 'Agile'  # or 'Scrum', 'CMMI', 'Basic'
SourceControlType = 'Git'  # or 'Tfvc'
Visibility = 'Private'     # or 'Public'

  3. Check naming conventions:

    # Avoid special characters
# Use alphanumeric + spaces, hyphens, underscores
# Keep names reasonable length (< 255 chars)

Permission Issues

Issue: "Cannot Assign Permission"

Symptoms:

  • Error: Failed to assign permission
  • Permission appears not to take effect
  • Different users see different permissions

Solutions:

  1. Verify group exists:

    # Ensure group is created before assigning permissions
DependsOn = '[AzDoOrganizationGroup]GroupName'

  2. Check permission name:

    # Use exact permission name
PermissionName = 'Create Project'  # Case matters

  3. Verify scope:

    # Organization-level: omit ProjectName
# Project-level: include ProjectName
# Namespace-level: use appropriate namespace

  4. Check allow/deny:

    # Deny takes precedence over Allow
# Inherited permissions may override
# Check parent group permissions

Issue: "Permission Not Taking Effect"

Symptoms:

  • Permission set but user still denied access
  • Test shows permission exists but doesn't work
  • Different behavior than expected

Solutions:

  1. Check inheritance:

    # Inherited permissions may be overridden
# Check parent groups and scopes
# May need to explicitly set instead of inherit

  2. Verify user assignment:

    # Ensure user is actually in the group
# Use AzDoGroupMember to add to group
# Check group membership in UI

  3. Wait for cache refresh:

    # Permissions cache may take 5-10 minutes
# Try accessing resource after delay
# Clear browser cache if using UI

  4. Check for conflicting denies:

    # Explicit deny overrides allow
# Check all parent groups and scopes
# Remove deny if incorrectly set

Configuration Issues

Issue: "Configuration Won't Apply"

Symptoms:

  • Configuration runs but makes no changes
  • Test method always returns true
  • Changes don't persist

Solutions:

  1. Check Ensure property:

    # Ensure = 'Present' by default
# If missing, configuration may do nothing
Ensure = 'Present'

  2. Enable verbose logging:

    Start-DscConfiguration -Path ./Config -Wait -Verbose -Force

  3. Check DSC logs:

    # View DSC event log
Get-WinEvent -LogName 'DSC/Operational' | 
    Where-Object Message -match 'Error' | 
    Select-Object TimeCreated, Message

  4. Verify authentication:

    # Ensure auth is properly set
# Check token/credentials are valid
# Verify access to required resources

Issue: "Properties Not Updating"

Symptoms:

  • Some properties change, others don't
  • Test method indicates resource matches
  • Manual changes revert

Solutions:

  1. Check property support:

    # Some properties may be read-only
# SourceControlType cannot be changed after creation
# May need to delete and recreate

  2. Use Set method explicitly:

    $properties = @{
    ProjectName = 'MyProject'
    ProjectDescription = 'New description'
}
Invoke-DscResource -Name 'AzDoProject' `
    -Method Set `
    -Property $properties

  3. Force reapplication:

    # Remove LCM cache
Remove-Item C:\Windows\System32\config\systemprofile\AppData\Local\`
    dsc\configuration -Recurse -Force
Start-DscConfiguration -Path ./Config -Force -Wait -Verbose

Performance Issues

Issue: "Configuration Runs Very Slowly"

Symptoms:

  • Configuration takes unusually long time
  • API calls time out
  • Memory usage increases

Solutions:

  1. Batch similar operations:

    # Create multiple resources of same type together
foreach ($project in $projectList) {
    AzDoProject "Project_$($project.Name)" {
        ProjectName = $project.Name
        # ...
    }
}

  2. Reduce API calls:

    # Combine operations where possible
# Avoid redundant Get operations
# Cache organizational data

  3. Use parallel execution:

    # Independent resources can run in parallel
# DSC automatically parallelizes when possible
# Ensure proper DependsOn for ordering

  4. Increase timeouts:

    # Some operations may need more time
# Check Azure DevOps load
# Consider throttling rate limits

Issue: "Rate Limiting / Throttling"

Symptoms:

  • Error: Rate limit exceeded
  • Error: Too many requests
  • API calls start failing

Solutions:

  1. Reduce concurrency:

    # Azure DevOps has API rate limits
# Add delays between operations
# Use sequential instead of parallel

  2. Implement backoff:

    # Wait before retrying failed operations
# Start small (1 second), exponential backoff
# Max reasonable wait (1-5 minutes)

  3. Request quota increase:

    # Contact Microsoft for higher limits
# Enterprise agreements may have higher limits
# Monitor usage patterns

General DSC Issues

Issue: "DSC Configuration Fails"

Symptoms:

  • Configuration fails to run
  • Compilation errors
  • Resource not found

Solutions:

  1. Verify module is imported:

    Import-DscResource -ModuleName 'AzureDevOpsDscNative'

# Check module is installed
Get-Module AzureDevOpsDscNative -ListAvailable

  2. Check PowerShell version:

    # Requires PowerShell 7.0+
$PSVersionTable.PSVersion

  3. Clear DSC cache:

    # Remove cached configurations
Remove-Item C:\Windows\System32\config\systemprofile\`
    AppData\Local\dsc\configuration -Recurse -Force

  4. Review syntax:

    # Check configuration syntax
# Verify all properties are valid
# Check for typos in resource names

Issue: "Get/Test/Set Method Fails"

Symptoms:

  • Get returns error
  • Test method throws exception
  • Set method fails silently

Solutions:

  1. Enable debug output:

    $DebugPreference = 'Continue'
Invoke-DscResource -Name 'AzDoProject' -Method Get -Property @{ProjectName='Test'}

  2. Check prerequisites:

    # Verify all dependencies are met
# Check required modules are installed
# Ensure authentication is working

  3. Test with Invoke-DscResource:

    # Test individual resource
Invoke-DscResource -Name 'AzDoProject' `
    -Method Test `
    -Property @{ProjectName='Test'; Ensure='Present'} `
    -ModuleName 'AzureDevOpsDscNative'

Getting More Help

If you can't find solution here:

  1. Check resource documentation: See Resources for specific resource help
  2. Review examples: Look for similar scenario in Examples
  3. Check Best Practices: See Best Practices for patterns
  4. Enable logging: Use verbose/debug output for more details
  5. Check Azure DevOps status: Verify service isn't having issues
  6. Report issue: File issue on GitHub with configuration and error details

Quick Reference

Common Errors:

  • 404 Not Found - Resource doesn't exist
  • 403 Forbidden - Insufficient permissions
  • 401 Unauthorized - Authentication failed
  • 409 Conflict - Resource name conflict
  • 400 Bad Request - Invalid property value
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Server Error - Azure DevOps service issue

Quick Fixes:

  1. Check authentication first
  2. Verify resource exists
  3. Confirm permissions
  4. Check property values
  5. Review dependencies
  6. Enable verbose logging
  7. Check Azure DevOps status
  8. Try again after delay

Clone this wiki locally