Troubleshooting Guide

This comprehensive troubleshooting guide helps you diagnose and resolve common issues with TenuVault. Whether you're experiencing backup failures, authentication problems, or portal issues, this guide provides step-by-step solutions.

Table of Contents

• Quick Diagnostics
• Authentication Issues
• Backup Failures
• Portal Access Problems
• Storage Issues
• Performance Problems
• Drift Detection Issues
• Recovery Problems
• Common Error Messages
• Advanced Troubleshooting
• FAQ
• Getting Additional Help

  Quick Diagnostics

  System Health Check

  Before diving into specific issues, run this quick health check:

  Portal Health Check

1. 1Navigate to Settings* → *System Health
2. 1Click Run Diagnostics
3. 1Review results:

Component Status

• Azure AD Authentication: Token validity, permissions
• Storage Account: Connectivity, permissions, space
• Automation Account: Runbook status, modules
• Key Vault: Access, secret retrieval
• Graph API: Rate limits, permissions

  Quick Fix Actions

1. 1Refresh Authentication: Settings → Authentication → Refresh Token
2. 1Clear Cache: Settings → Advanced → Clear Portal Cache
3. 1Restart Services: Azure Portal → App Service → Restart
4. 1Sync Permissions: Settings → Permissions → Sync Now

   Diagnostic Information Collection

   When issues persist, collect this information:

   System Information

# Run in PowerShell
Get-Date
$PSVersionTable
Get-AzContext
Get-AzSubscription
Get-AzResource -ResourceGroupName "rg-tenuvault"

Portal Logs

1. 1Azure Portal → App Service → Log Stream
2. 1Application Insights → Failures
3. 1Storage Account → Diagnostics
4. 1Automation Account → Job History

   Authentication Issues

   Issue: Cannot Sign In to Portal

   Symptoms

• Login page redirects back without signing in
• "Authentication failed" error
• Infinite redirect loop

  Solutions

  Solution 1: Clear Browser Data

1. 1Clear cookies for your portal domain
2. 1Clear browser cache
3. 1Try incognito/private browsing
4. 1Try different browser

   Solution 2: Check Azure AD Configuration

5. 1Verify app registration exists:

   Get-AzADApplication -DisplayName "TenuVault-Backup-Service"
   

1. 1Check redirect URIs:

1. 1Verify authentication settings in App Service

   Solution 3: Reset Authentication

2. 1Azure Portal → App Service
3. 1Authentication → Edit
4. 1Remove and re-add Azure AD provider
5. 1Save and restart App Service

   Issue: "Insufficient Permissions" Error

   Symptoms

• Can log in but see permission errors
• "Access denied" messages
• Missing features in portal

  Solutions

  Solution 1: Verify User Permissions

# Check user's Azure AD roles
Get-AzRoleAssignment -SignInName "user@domain.com"

# Check app permissions
Get-AzADApplication -DisplayName "TenuVault" | 
  Get-AzADAppPermission

Solution 2: Grant Required Permissions

1. 1Azure AD → App Registrations → TenuVault
2. 1API Permissions → Add permissions:

1. 1Click "Grant admin consent"

   Solution 3: Check Conditional Access

• Review Conditional Access policies
• Ensure TenuVault app is not blocked
• Check for MFA requirements
• Verify device compliance requirements

  Issue: Token Expiration

  Symptoms

• Random logouts
• "Token expired" errors
• Need to login frequently

  Solutions

  Solution 1: Extend Token Lifetime

1. 1Azure AD → App Registrations → TenuVault
2. 1Token configuration → Add optional claim
3. 1Set token lifetime policy:

   $policy = New-AzureADPolicy -Definition @('{"TokenLifetimePolicy":{"Version":1,"AccessTokenLifetime":"04:00:00"}}') -DisplayName "TenuVaultTokenPolicy" -IsOrganizationDefault $false -Type "TokenLifetimePolicy"
   

Solution 2: Enable Token Refresh

1. 1Portal Settings → Authentication
2. 1Enable "Keep me signed in"
3. 1Configure refresh token settings

   Backup Failures

   Issue: Backup Jobs Not Starting

   Symptoms

• Scheduled backups don't run
• Manual backups won't start
• No job history entries

  Solutions

  Solution 1: Check Automation Account

# Check automation account status
Get-AzAutomationAccount -ResourceGroupName "rg-tenuvault"

# Check runbook status
Get-AzAutomationRunbook -AutomationAccountName "aa-tenuvault" -ResourceGroupName "rg-tenuvault"

# Check schedule
Get-AzAutomationSchedule -AutomationAccountName "aa-tenuvault" -ResourceGroupName "rg-tenuvault"

Solution 2: Verify Runbook Configuration

1. 1Open Automation Account in Azure Portal
2. 1Check Runbooks → Backup-IntuneConfiguration
3. 1Verify it's Published (not in Draft)
4. 1Test with Test Pane

   Solution 3: Check Schedule Linking

# Link schedule to runbook
Register-AzAutomationScheduledRunbook `
  -AutomationAccountName "aa-tenuvault" `
  -ResourceGroupName "rg-tenuvault" `
  -RunbookName "Backup-IntuneConfiguration" `
  -ScheduleName "DailyBackup"

Issue: Backup Fails Mid-Execution

Symptoms

• Backup starts but fails partway
• Partial backup files created
• Error in job history

  Common Error Messages and Solutions

  "Unauthorized" or "401" Error

• Client secret expired
• Update secret in Key Vault:

  $secret = ConvertTo-SecureString "new-secret-value" -AsPlainText -Force
  Set-AzKeyVaultSecret -VaultName "kv-tenuvault" -Name "ClientSecret" -SecretValue $secret
  

"Too Many Requests" or "429" Error

• Graph API throttling
• Solutions:

"Storage Access Denied"

• Check storage permissions:

  # Grant automation account access to storage
  New-AzRoleAssignment `
    -ObjectId (Get-AzAutomationAccount -ResourceGroupName "rg-tenuvault" -Name "aa-tenuvault").Identity.PrincipalId `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope "/subscriptions/{sub-id}/resourceGroups/rg-tenuvault/providers/Microsoft.Storage/storageAccounts/sttenuvault"
  

Issue: Incomplete Backups

Symptoms

• Some policies missing from backup
• Backup completes but with warnings
• File count doesn't match expectation

  Solutions

  Solution 1: Check API Permissions

• DeviceManagementConfiguration.ReadWrite.All
• DeviceManagementApps.ReadWrite.All
• DeviceManagementServiceConfig.ReadWrite.All

  Solution 2: Increase Timeout

1. 1Automation Account → Runbook → Edit
2. 1Modify timeout settings:

   $TimeoutSeconds = 3600  # Increase from default
   

Solution 3: Check Specific Policy Types Some policy types might need additional permissions:

# Test specific API access
$token = Get-AzAccessToken -ResourceUrl "https://graph.microsoft.com"
$headers = @{Authorization = "Bearer $($token.Token)"}

# Test each endpoint
Invoke-RestMethod -Uri "https://graph.microsoft.com/v1.0/deviceManagement/deviceConfigurations" -Headers $headers

Portal Access Problems

Issue: Portal Won't Load

Symptoms

• Blank page
• 500/503 errors
• Timeout errors
• "Site can't be reached"

  Solutions

  Solution 1: Check App Service Status

# Check App Service health
Get-AzWebApp -ResourceGroupName "rg-tenuvault" -Name "tenuvault-portal"

# Restart App Service
Restart-AzWebApp -ResourceGroupName "rg-tenuvault" -Name "tenuvault-portal"

Solution 2: Review Application Logs

1. 1Azure Portal → App Service → Log Stream
2. 1Look for startup errors
3. 1Check Application Insights for exceptions

   Solution 3: Check Network Configuration

• Verify DNS resolution
• Check firewall rules
• Review Network Security Groups
• Validate SSL certificate

  Issue: Slow Portal Performance

  Symptoms

• Pages load slowly
• Timeouts on operations
• Unresponsive interface

  Solutions

  Solution 1: Scale App Service

# Scale up App Service Plan
Set-AzAppServicePlan `
  -ResourceGroupName "rg-tenuvault" `
  -Name "asp-tenuvault" `
  -Tier "Standard" `
  -WorkerSize "Medium"

Solution 2: Optimize Database Queries

• Check Application Insights → Performance
• Identify slow queries
• Add appropriate indexes
• Consider caching frequently accessed data

  Solution 3: Enable CDN

1. 1Create CDN profile
2. 1Configure endpoint for static assets
3. 1Update portal to use CDN URLs

   Storage Issues

   Issue: "Storage Full" Errors

   Symptoms

• Backup fails with storage errors
• "Insufficient space" messages
• Storage quota exceeded

  Solutions

  Solution 1: Check Storage Usage

# Get storage account usage
$storageAccount = Get-AzStorageAccount -ResourceGroupName "rg-tenuvault" -Name "sttenuvault"
$ctx = $storageAccount.Context
Get-AzStorageUsage -Context $ctx

Solution 2: Implement Retention Policies

# Set lifecycle management rules
$action = Add-AzStorageAccountManagementPolicyAction -Delete -DaysAfterModificationGreaterThan 90
$filter = New-AzStorageAccountManagementPolicyFilter -PrefixMatch @("backups/")
$rule = New-AzStorageAccountManagementPolicyRule -Name "DeleteOldBackups" -Action $action -Filter $filter
Set-AzStorageAccountManagementPolicy -ResourceGroupName "rg-tenuvault" -AccountName "sttenuvault" -Rule $rule

Solution 3: Archive Old Backups Move old backups to archive tier:

# Move blobs to archive tier
$blobs = Get-AzStorageBlob -Container "intune-backups" -Context $ctx
foreach ($blob in $blobs) {
    if ($blob.LastModified -lt (Get-Date).AddDays(-30)) {
        $blob.ICloudBlob.SetStandardBlobTier("Archive")
    }
}

Issue: Storage Access Denied

Symptoms

• Cannot read/write backup files
• Permission denied errors
• 403 Forbidden responses

  Solutions

  Solution 1: Check Storage Firewall

# Allow Azure services
Update-AzStorageAccountNetworkRuleSet `
  -ResourceGroupName "rg-tenuvault" `
  -Name "sttenuvault" `
  -Bypass AzureServices

Solution 2: Regenerate Storage Keys

# Regenerate and update keys
$keys = New-AzStorageAccountKey -ResourceGroupName "rg-tenuvault" -Name "sttenuvault" -KeyName key1
# Update connection strings in App Service and Automation Account

Solution 3: Use Managed Identity Switch to managed identity for authentication:

1. 1Enable managed identity on App Service
2. 1Grant Storage Blob Data Contributor role
3. 1Update application to use DefaultAzureCredential

   Performance Problems

   Issue: Slow Backup Performance

   Symptoms

• Backups take hours
• Timeout errors
• High resource consumption

  Solutions

  Solution 1: Optimize API Calls

# Use batch operations where possible
# Instead of individual calls, use:
$filter = "`$top=999"
$policies = Invoke-MgGraphRequest -Uri "https://graph.microsoft.com/v1.0/deviceManagement/deviceConfigurations?$filter"

Solution 2: Implement Parallel Processing

# Process policies in parallel
$policies | ForEach-Object -Parallel {
    # Process each policy
} -ThrottleLimit 5

Solution 3: Use Incremental Backups Only backup changed items:

# Compare with last backup
$lastBackup = Get-LastBackupMetadata
$currentState = Get-CurrentIntuneState
$changes = Compare-Object $lastBackup $currentState -Property Id
# Only backup changed items

Drift Detection Issues

Issue: False Positive Drift Alerts

Symptoms

• Alerts for no actual changes
• System-generated changes flagged
• Too many notifications

  Solutions

  Solution 1: Tune Detection Rules

1. 1Portal → Drift Detection → Rules
2. 1Add exclusions for:

Solution 2: Update Baseline

# Set new baseline after verified changes
Set-DriftBaseline -TenantId $tenantId -BackupId $latestBackupId

Solution 3: Configure Ignore Patterns Add ignore patterns for known changes:

{
  "ignorePatterns": [
    "*.lastModifiedDateTime",
    "*.version",
    "@odata.*"
  ]
}

Issue: Drift Not Being Detected

Symptoms

• Known changes not reported
• Drift detection seems inactive
• No alerts despite changes

  Solutions

  Solution 1: Check Detection Schedule

# Verify drift detection is enabled and scheduled
Get-AzAutomationSchedule -AutomationAccountName "aa-tenuvault" -ResourceGroupName "rg-tenuvault" | 
  Where-Object {$_.Name -like "*drift*"}

Solution 2: Verify Baseline Exists Ensure baseline is set:

# Check for baseline
$baseline = Get-DriftBaseline -TenantId $tenantId
if (-not $baseline) {
    Set-DriftBaseline -TenantId $tenantId -BackupId $backupId
}

Recovery Problems

Issue: Restore Fails

Symptoms

• Restore operation errors
• Partial restoration
• Policies not appearing after restore

  Solutions

  Solution 1: Verify Permissions

# Add required Graph permissions
$sp = Get-AzADServicePrincipal -DisplayName "TenuVault"
Add-AzADAppPermission -ObjectId $sp.Id -ApiId "00000003-0000-0000-c000-000000000000" `
  -PermissionId "DeviceManagementConfiguration.ReadWrite.All"

Solution 2: Check Policy Compatibility Some policies might not be compatible:

• Platform version differences
• Deprecated settings
• Regional restrictions

  Solution 3: Use Selective Restore

foreach ($policy in $backupPolicies) {
    try {
        Restore-IntunePolicy -Policy $policy
        Write-Host "Restored: $($policy.displayName)" -ForegroundColor Green
    } catch {
        Write-Host "Failed: $($policy.displayName) - $_" -ForegroundColor Red
    }
}

Common Error Messages

Error Reference Table

Detailed Error Solutions

"InvalidAuthenticationToken"

# Refresh token
$context = Get-AzContext
$token = Get-AzAccessToken -ResourceUrl "https://graph.microsoft.com"

# Update in Key Vault
$secret = ConvertTo-SecureString $token.Token -AsPlainText -Force
Set-AzKeyVaultSecret -VaultName "kv-tenuvault" -Name "GraphToken" -SecretValue $secret

"TooManyRequests"

$retryCount = 0
$maxRetries = 5
do {
    try {
        # Your API call here
        $result = Invoke-RestMethod -Uri $uri -Headers $headers
        break
    } catch {
        if ($_.Exception.Response.StatusCode -eq 429 -and $retryCount -lt $maxRetries) {
            $retryAfter = $_.Exception.Response.Headers["Retry-After"]
            Start-Sleep -Seconds ([Math]::Pow(2, $retryCount) * 10)
            $retryCount++
        } else {
            throw
        }
    }
} while ($retryCount -lt $maxRetries)

Advanced Troubleshooting

Enable Debug Logging

Portal Debug Mode

1. 1Settings → Advanced → Debug Mode
2. 1Enable verbose logging
3. 1Reproduce issue
4. 1Download debug logs

   PowerShell Debug

# Enable debug output
$DebugPreference = "Continue"
$VerbosePreference = "Continue"

# Run commands with -Debug and -Verbose
Get-IntuneBackup -Debug -Verbose

Analyze Application Insights

Query Examples

// Find all errors in last 24 hours
exceptions
| where timestamp > ago(24h)
| order by timestamp desc

// Slow requests
requests
| where duration > 5000
| order by duration desc

// Failed dependencies
dependencies
| where success == false
| order by timestamp desc

Network Tracing

Using Fiddler

1. 1Install Fiddler
2. 1Configure HTTPS decryption
3. 1Capture traffic during issue
4. 1Analyze requests/responses

   Browser Developer Tools

5. 1F12 to open dev tools
6. 1Network tab
7. 1Reproduce issue
8. 1Export HAR file for analysis

   FAQ

   General Questions

   Q: How often should I backup?

Q: How much storage do I need? A: Typically 1-5 GB for most organizations. Plan for 3-6 months retention.

Q: Can I backup multiple tenants? A: Yes, TenuVault supports unlimited tenants in a single deployment.

Q: Is my data encrypted? A: Yes, data is encrypted at rest in Azure Storage and in transit using TLS.

Backup Questions

Q: Why are some policies missing from backups? A: Check Graph API permissions. Some policy types require specific permissions.

Q: Can I exclude certain policies? A: Yes, configure exclusion rules in the backup configuration.

Q: How do I backup Conditional Access policies? A: Conditional Access requires additional permissions and separate backup configuration.

Recovery Questions

Q: Can I restore to a different tenant? A: Yes, but ensure the target tenant has the same features and licenses.

Q: How long does restoration take? A: Typically 5-30 minutes depending on the number of policies.

Q: Can I preview changes before restoring? A: Yes, use the preview feature to see what will change.

Performance Questions

Q: Why are backups slow? A: Could be API throttling, large policy count, or network issues. Check the performance section.

Q: How can I speed up backups? A: Use incremental backups, optimize API calls, and ensure adequate resources.

Q: Is there a limit on backup frequency? A: No hard limit, but consider API rate limits and storage costs.

Getting Additional Help

Self-Service Resources

Documentation

• Getting Started Guide
• User Guide
• Best Practices Guide
• Portal deployment and app registration

  Community Resources

• GitHub Issues: Report bugs and request features
• Discord Server: Real-time community help
• Stack Overflow: Tagged questions and answers
• YouTube: Video tutorials and walkthroughs

  Support Channels

  Community Support (Free)

• GitHub Discussions
• Discord Community
• Reddit: r/TenuVault
• Twitter: @TenuVault

  Professional Support

• Email: support@tenuvault.com
• Priority support tickets
• Remote assistance
• Custom training sessions

  Diagnostic Information to Provide

  When seeking help, provide:

  1. Error Details

2. Environment Information - TenuVault version - Azure region - Browser/OS - Network configuration

3. Logs - Portal error logs - Browser console logs - Application Insights traces - PowerShell error output

4. Configuration - Sanitized backup configuration - Schedule settings - Permission configuration - Recent changes

Emergency Support

For critical production issues:

1. Immediate Actions - Check system health dashboard - Review recent changes - Attempt quick fixes - Document everything

2. Escalation Path - Community Discord: #emergency-help - Email: emergency@tenuvault.com - Phone: Available for enterprise customers

3. Temporary Workarounds - Use PowerShell module for manual backups - Export configurations manually - Pause automated operations - Switch to backup instance

Remember: Most issues can be resolved using this guide. Take time to work through the relevant sections before escalating.

---

For optimization recommendations, see the Best Practices Guide. For feature documentation, refer to the User Guide.