claude-skills-reference/engineering-team/ms365-tenant-manager/references/troubleshooting.md

Troubleshooting Guide

Common issues and solutions for Microsoft 365 tenant administration.

---

Table of Contents

• Authentication Errors
• PowerShell Module Issues
• Permission Problems
• License Assignment Failures
• DNS and Domain Issues
• Conditional Access Lockouts
• Mailbox Issues

---

Authentication Errors

"AADSTS50076: MFA Required"

Cause: User requires MFA but hasn't completed it.

Solutions:

1. Complete MFA registration at https://aka.ms/mfasetup
2. Use interactive authentication:

   Connect-MgGraph -Scopes "User.Read.All" -UseDeviceAuthentication
   

3. Check Conditional Access policies excluding the user

"AADSTS65001: User hasn't consented"

Cause: Application requires permissions user hasn't granted.

Solutions:

1. Grant admin consent in Azure AD portal
2. Use admin account for initial consent:

   Connect-MgGraph -Scopes "User.ReadWrite.All" -ContextScope Process
   

3. Add application to enterprise applications with pre-consent

"AADSTS700016: Application not found"

Cause: App registration missing or incorrect tenant.

Solutions:

1. Verify app ID in Azure AD > App registrations
2. Check multi-tenant setting if cross-tenant
3. Re-register application if needed

"Access Denied" Despite Admin Role

Causes:

• PIM role not activated
• Role assignment pending
• Conditional Access blocking

Solutions:

1. Activate PIM role:
   • Go to Azure AD > Privileged Identity Management
   • Activate required role
2. Wait 5-10 minutes for role propagation
3. Check Conditional Access policies in report-only mode

---

PowerShell Module Issues

Module Not Found

Error: The term 'Connect-MgGraph' is not recognized

Solutions:

# Install module
Install-Module Microsoft.Graph -Scope CurrentUser -Force

# If already installed, import explicitly
Import-Module Microsoft.Graph

# Check installation
Get-InstalledModule Microsoft.Graph

Module Version Conflicts

Error: Assembly with same name already loaded

Solutions:

# Remove all versions
Get-Module Microsoft.Graph* | Remove-Module -Force

# Clear cache
Remove-Item "$env:USERPROFILE\.local\share\powershell\*" -Recurse -Force

# Reinstall
Install-Module Microsoft.Graph -Force -AllowClobber

Exchange Online Connection Failures

Error: Connecting to remote server failed

Solutions:

# Use modern authentication
Connect-ExchangeOnline -UserPrincipalName admin@tenant.com

# If MFA issues, use device code
Connect-ExchangeOnline -Device

# Check WinRM service
Get-Service WinRM | Start-Service

Graph API Throttling

Error: 429 Too Many Requests

Solutions:

1. Implement retry logic:

   $retryCount = 0
   $maxRetries = 3
   do {
       try {
           $result = Get-MgUser -All
           break
       } catch {
           if ($_.Exception.Response.StatusCode -eq 429) {
               $retryAfter = $_.Exception.Response.Headers['Retry-After']
               Start-Sleep -Seconds ([int]$retryAfter + 5)
               $retryCount++
           } else { throw }
       }
   } while ($retryCount -lt $maxRetries)
   

2. Reduce batch sizes
3. Use delta queries for incremental updates

---

Permission Problems

Insufficient Privileges for User Creation

Error: Insufficient privileges to complete the operation

Required Permissions:

• User Administrator role
• OR User.ReadWrite.All Graph permission

Solutions:

1. Verify role assignment:

   Get-MgDirectoryRoleMember -DirectoryRoleId (Get-MgDirectoryRole -Filter "displayName eq 'User Administrator'").Id
   

2. Request role assignment or PIM activation
3. Use service principal with appropriate permissions

Cannot Modify Another Admin

Error: Cannot update privileged user

Cause: Attempting to modify user with equal or higher privileges.

Solutions:

1. Use account with higher privilege level
2. Global Admin required to modify other Global Admins
3. Remove target's admin role first (if appropriate)

Application Permission vs Delegated

Issue: Script works interactively but fails in automation

Solution: Use application permissions for automation:

# Application authentication (daemon/service)
$clientId = "app-id"
$tenantId = "tenant-id"
$clientSecret = ConvertTo-SecureString "secret" -AsPlainText -Force
$credential = New-Object System.Management.Automation.PSCredential($clientId, $clientSecret)

Connect-MgGraph -ClientSecretCredential $credential -TenantId $tenantId

---

License Assignment Failures

"Usage location must be specified"

Error: License assignment failed because UsageLocation is not set

Solution:

# Set usage location before license assignment
Update-MgUser -UserId user@tenant.com -UsageLocation "US"

# Then assign license
$license = @{
    AddLicenses = @(@{SkuId = "sku-id"})
    RemoveLicenses = @()
}
Set-MgUserLicense -UserId user@tenant.com -BodyParameter $license

"No available licenses"

Error: License quota exceeded

Solutions:

1. Check available licenses:

   Get-MgSubscribedSku | Select-Object SkuPartNumber,
       @{N='Available';E={$_.PrepaidUnits.Enabled - $_.ConsumedUnits}}
   

2. Remove licenses from inactive users
3. Purchase additional licenses

Conflicting Service Plans

Error: Conflicting service plans

Cause: User has license with overlapping services.

Solution:

# Check current licenses
Get-MgUserLicenseDetail -UserId user@tenant.com |
    Select-Object SkuPartNumber, @{N='Plans';E={$_.ServicePlans.ServicePlanName}}

# Remove conflicting license first
$remove = @{
    AddLicenses = @()
    RemoveLicenses = @("conflicting-sku-id")
}
Set-MgUserLicense -UserId user@tenant.com -BodyParameter $remove

# Then add new license

---

DNS and Domain Issues

Domain Verification Failing

Error: Domain verification record not found

Solutions:

1. Verify TXT record:

   nslookup -type=TXT domain.com
   

2. Check for typos in record value
3. Wait 24-48 hours for propagation
4. Try alternate verification (MX record)

MX Record Not Resolving

Error: Mail flow disrupted

Diagnostic:

nslookup -type=MX domain.com
# Should return: domain.com.mail.protection.outlook.com

Solutions:

1. Verify MX record points to domain.com.mail.protection.outlook.com
2. Priority should be 0 or lowest number
3. Remove conflicting MX records

SPF Record Issues

Error: SPF validation failed

Correct SPF:

v=spf1 include:spf.protection.outlook.com -all

Common Mistakes:

• Multiple SPF records (only one allowed)
• Missing -all or using ~all
• Too many DNS lookups (max 10)

Check:

nslookup -type=TXT domain.com | findstr spf

---

Conditional Access Lockouts

Locked Out by MFA Policy

Symptoms: Cannot sign in, MFA loop

Immediate Actions:

1. Use emergency access account
2. Sign in from trusted location/device
3. Contact admin to temporarily exclude user

Resolution:

# Add user to CA exclusion group
$group = Get-MgGroup -Filter "displayName eq 'CA-Excluded-Users'"
New-MgGroupMember -GroupId $group.Id -DirectoryObjectId (Get-MgUser -UserId user@tenant.com).Id

Policy Conflicts

Symptoms: Unexpected blocks, inconsistent behavior

Diagnostic:

1. Check sign-in logs: Azure AD > Sign-in logs
2. Filter by user, check "Conditional Access" tab
3. Review which policies applied/failed

Resolution:

1. Review all policies in report-only mode
2. Check for conflicting conditions
3. Ensure proper policy ordering

Break-Glass Procedure

When to use: Complete admin lockout

Steps:

1. Sign in with emergency access account
2. Go to Azure AD > Security > Conditional Access
3. Set all policies to "Report-only"
4. Diagnose and fix root cause
5. Re-enable policies gradually

---

Mailbox Issues

Mailbox Not Provisioning

Error: Mailbox doesn't exist

Causes:

• License not assigned
• License assignment pending
• User created without Exchange license

Solutions:

1. Verify license:

   Get-MgUserLicenseDetail -UserId user@tenant.com
   

2. Wait 5-10 minutes after license assignment
3. Force mailbox provisioning:

   # Reassign license
   Set-MgUserLicense -UserId user@tenant.com -BodyParameter @{
       RemoveLicenses = @("sku-id")
       AddLicenses = @()
   }
   Start-Sleep -Seconds 60
   Set-MgUserLicense -UserId user@tenant.com -BodyParameter @{
       AddLicenses = @(@{SkuId = "sku-id"})
       RemoveLicenses = @()
   }
   

Mailbox Size Limit

Error: Mailbox quota exceeded

Solutions:

# Check current quota
Get-Mailbox user@tenant.com | Select-Object ProhibitSendQuota, ProhibitSendReceiveQuota

# Increase quota (if license allows)
Set-Mailbox user@tenant.com -ProhibitSendQuota 99GB -ProhibitSendReceiveQuota 100GB

# Or enable archive
Enable-Mailbox user@tenant.com -Archive

Mail Flow Issues

Diagnostic:

# Test mail flow
Test-Mailflow -TargetEmailAddress external@gmail.com

# Check mail flow rules
Get-TransportRule | Where-Object {$_.State -eq 'Enabled'} | Select-Object Name, Priority, Conditions

# Check connectors
Get-InboundConnector
Get-OutboundConnector

Common Fixes:

1. Check transport rules for blocks
2. Verify connector configuration
3. Check ATP/spam policies
4. Review quarantine for false positives