TroubleshootingDecember 1, 2025

Troubleshooting Common Issues

Solutions to common problems encountered during Microsoft 365 group migrations.

Troubleshooting

This guide helps you resolve common issues encountered during migrations.

Connection Issues

Problem: Cannot Connect to Source Tenant

Symptoms:

Error: Failed to authenticate with source tenant
AADSTS50076: Due to a configuration change...

Solutions:

  1. Verify credentials are correct:

    Test-PrimeraConnection -TenantId "source.onmicrosoft.com"

  2. Check MFA requirements:

    • Use app password for MFA-enabled accounts
    • Or use certificate-based authentication

  3. Verify network connectivity:

    Test-NetConnection -ComputerName login.microsoftonline.com -Port 443

Problem: Intermittent Disconnections

Cause: Token expiration or network issues

Solution:

# Enable auto-reconnect
Set-PrimeraConfig -AutoReconnect $true -ReconnectAttempts 3

Permission Errors

Problem: Insufficient Permissions

Error message:

Error: Forbidden - Insufficient privileges to complete the operation

Required permissions checklist:

  • [ ] Group.ReadWrite.All
  • [ ] Directory.ReadWrite.All
  • [ ] User.Read.All
  • [ ] Exchange Online Organization Management

Verify permissions:

Get-PrimeraPermissions -TenantId "your-tenant.onmicrosoft.com"

Problem: Admin Consent Required

Solution:

# Grant admin consent via PowerShell
Connect-AzureAD
New-AzureADServiceAppRoleAssignment `
    -ObjectId $servicePrincipalId `
    -PrincipalId $servicePrincipalId `
    -ResourceId $graphResourceId `
    -Id $appRoleId

Migration Failures

Problem: Groups Fail to Migrate

Common causes:

  1. Naming conflicts:

    # Check for conflicts
Get-PrimeraConflicts -PlanId "plan-001"

# Resolve with rename strategy
Set-PrimeraConflictPolicy -Strategy "Rename" -Suffix "-New"

  2. Missing dependencies:

    # Check dependencies
Get-PrimeraGroupDependencies -GroupId "group-id"

# Include dependencies in migration
Add-PrimeraDependencies -PlanId "plan-001" -AutoInclude

  3. Size limitations:

    • Maximum group size: 25,000 members
    • Solution: Split large groups or use dynamic groups

Problem: Partial Migration Success

Symptoms: Some objects migrate, others don't

Diagnosis:

# Get detailed migration log
Get-PrimeraMigrationLog -PlanId "plan-001" -Level "Error"

# Check failed items
Get-PrimeraFailedItems -PlanId "plan-001"

Retry failed items:

Retry-PrimeraMigration -PlanId "plan-001" -FailedOnly

Performance Issues

Problem: Slow Migration Speed

Optimization steps:

  1. Increase batch size:

    Set-PrimeraMigrationConfig -BatchSize 100 -ParallelTasks 10

  2. Schedule during off-peak:

    Start-PrimeraMigration -PlanId "plan-001" -Schedule "2AM-6AM"

  3. Check throttling:

    Get-PrimeraThrottlingStatus

Problem: API Rate Limiting

Error:

Error: Request rate limit exceeded (429 Too Many Requests)

Solution:

# Enable automatic throttling detection
Set-PrimeraConfig -AutoThrottle $true -ThrottleDelay 60

# Reduce parallel operations
Set-PrimeraMigrationConfig -ParallelTasks 3

Data Integrity Issues

Problem: Missing Group Members

Verification:

# Compare source and destination
Compare-PrimeraGroups `
    -SourceGroup "source-group-id" `
    -DestinationGroup "dest-group-id"

# Get member diff
Get-PrimeraGroupMemberDiff -PlanId "plan-001"

Fix:

# Sync missing members
Sync-PrimeraGroupMembers -GroupId "group-id" -Direction "SourceToDestination"

Problem: Permissions Not Migrated

Check:

# Verify permission migration
Test-PrimeraGroupPermissions -GroupId "group-id"

Manually copy permissions:

Copy-PrimeraGroupPermissions `
    -SourceGroupId "source-id" `
    -DestinationGroupId "dest-id"

Rollback Procedures

Complete Rollback

Remove migrated groups:

# Preview rollback
Test-PrimeraRollback -PlanId "plan-001" -WhatIf

# Execute rollback
Start-PrimeraRollback -PlanId "plan-001" -Confirm:$false

Partial Rollback

Rollback specific groups:

Undo-PrimeraGroupMigration -GroupId "group-1","group-2","group-3"

Log Analysis

Enable Detailed Logging

Set-PrimeraLogLevel -Level "Verbose"
Set-PrimeraLogPath -Path "C:\Logs\Migration"

Common Log Patterns

Authentication failures:

PATTERN: "AADSTS\d+"
ACTION: Check credentials and permissions

Throttling:

PATTERN: "429|Too Many Requests"
ACTION: Reduce batch size, add delays

Conflicts:

PATTERN: "already exists|duplicate"
ACTION: Review conflict resolution policy

Getting Additional Help

Diagnostic Collection

# Generate diagnostic package
New-PrimeraDiagnosticPackage -OutputPath "C:\Diagnostics\migration.zip"

Contact Support

Include the following information:

  1. Diagnostic package (generated above)
  2. Migration plan ID
  3. Error messages (full text)
  4. Tenant IDs (source and destination)
  5. Timeline (when issue occurred)

Support channels:

  • Email: support@primeralabs.tech
  • Portal: https://support.primeralabs.tech
  • Emergency: Available in your account dashboard

Known Issues

Issue: Dynamic DL Filter Conversion

Status: In Progress
Workaround: Manually recreate filters post-migration

Issue: Nested Groups > 5 Levels

Status: Limitation
Workaround: Flatten group structure before migration

Issue: On-Premises Group Sync Delay

Status: By Design
Note: Allow up to 30 minutes for sync

Next Steps