15 min read

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.

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

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

- 🟢 Green: Component functioning normally - 🟡 Yellow: Warning, needs attention - 🔴 Red: Critical issue requiring immediate action

Component Status

Check each component:

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

For common issues, try:

1Refresh Authentication: Settings → Authentication → Refresh Token
1Clear Cache: Settings → Advanced → Clear Portal Cache
1Restart Services: Azure Portal → App Service → Restart
1Sync Permissions: Settings → Permissions → Sync Now
Diagnostic Information Collection
When issues persist, collect this information:
System Information

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

Portal Logs

1Azure Portal → App Service → Log Stream
1Application Insights → Failures
1Storage Account → Diagnostics
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

1Clear cookies for your portal domain
1Clear browser cache
1Try incognito/private browsing
1Try different browser
Solution 2: Check Azure AD Configuration
1Verify app registration exists:

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

1Check redirect URIs:

- Should include: https://[your-portal].azurewebsites.net/.auth/login/aad/callback

1Verify authentication settings in App Service
Solution 3: Reset Authentication
1Azure Portal → App Service
1Authentication → Edit
1Remove and re-add Azure AD provider
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

powershell
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

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

- Microsoft Graph (Application): - DeviceManagementConfiguration.ReadWrite.All - DeviceManagementApps.ReadWrite.All - DeviceManagementServiceConfig.ReadWrite.All

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

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

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

Solution 2: Enable Token Refresh

1Portal Settings → Authentication
1Enable "Keep me signed in"
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

powershell
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

1Open Automation Account in Azure Portal
1Check Runbooks → Backup-IntuneConfiguration
1Verify it's Published (not in Draft)
1Test with Test Pane
Solution 3: Check Schedule Linking

powershell
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:
  powershell
  $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:
  1. Reduce backup frequency
  2. Implement retry logic
  3. Add delays between API calls
  4. Use incremental backups
"Storage Access Denied"
Check storage permissions:
  powershell
  # 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
Ensure all required Graph permissions are granted:
DeviceManagementConfiguration.ReadWrite.All
DeviceManagementApps.ReadWrite.All
DeviceManagementServiceConfig.ReadWrite.All
Solution 2: Increase Timeout
1Automation Account → Runbook → Edit
1Modify timeout settings:

powershell $TimeoutSeconds = 3600 # Increase from default

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

powershell

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

powershell

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
1Azure Portal → App Service → Log Stream
1Look for startup errors
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

powershell

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
1Create CDN profile
1Configure endpoint for static assets
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

powershell

Get storage account usage

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

Solution 2: Implement Retention Policies

powershell

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:

powershell

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

powershell

Allow Azure services

Update-AzStorageAccountNetworkRuleSet


  -ResourceGroupName "rg-tenuvault"

-Name "sttenuvault"


  -Bypass AzureServices
Solution 2: Regenerate Storage Keys
powershell
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:
1Enable managed identity on App Service
1Grant Storage Blob Data Contributor role
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
powershell
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

powershell

Process policies in parallel

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

Solution 3: Use Incremental Backups Only backup changed items:

powershell

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 1Portal → Drift Detection → Rules 1Add exclusions for: - System-modified timestamps - Version auto-increments - Computed properties

Solution 2: Update Baseline

powershell

Set new baseline after verified changes

Set-DriftBaseline -TenantId $tenantId -BackupId $latestBackupId

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

json { "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

powershell

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:

powershell

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
Ensure service principal has write permissions:

powershell

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
Restore policies one at a time to identify issues:
powershell
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
Error Message Cause Solution

"InvalidAuthenticationToken" Token expired or invalid Refresh authentication token
"Request_ResourceNotFound" Policy/resource doesn't exist Verify resource exists in Intune
"TooManyRequests" API rate limiting Implement retry logic with backoff
"InsufficientPrivileges" Missing permissions Grant required Graph permissions
"StorageException" Storage account issues Check storage connectivity and permissions
"TimeoutException" Operation taking too long Increase timeout or optimize operation
"InvalidRequest" Malformed API request Check API payload format
"ConflictError" Resource already exists Use update instead of create
"QuotaExceeded" Limit reached Check subscription limits
"NetworkError" Connectivity issues Verify network configuration
Detailed Error Solutions
"InvalidAuthenticationToken"
powershell
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"
Implement exponential backoff:
powershell
$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
1Settings → Advanced → Debug Mode
1Enable verbose logging
1Reproduce issue
1Download debug logs
PowerShell Debug
powershell
Enable debug output
$DebugPreference = "Continue"
$VerbosePreference = "Continue"
Run commands with -Debug and -Verbose
Get-IntuneBackup -Debug -Verbose
Analyze Application Insights
Query Examples
kusto
// 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

1Install Fiddler
1Configure HTTPS decryption
1Capture traffic during issue
1Analyze requests/responses
Browser Developer Tools
1F12 to open dev tools
1Network tab
1Reproduce issue
1Export HAR file for analysis
FAQ
General Questions
Q: How often should I backup?

A: Daily backups are recommended for production environments. High-change environments might need hourly backups.

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
API Documentation
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

- Exact error message - Screenshot if applicable - Time of occurrence - Steps to reproduce

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.

Drift Detection Best Practices

"InvalidAuthenticationToken"	Token expired or invalid	Refresh authentication token
"Request_ResourceNotFound"	Policy/resource doesn't exist	Verify resource exists in Intune
"TooManyRequests"	API rate limiting	Implement retry logic with backoff
"InsufficientPrivileges"	Missing permissions	Grant required Graph permissions
"StorageException"	Storage account issues	Check storage connectivity and permissions
"TimeoutException"	Operation taking too long	Increase timeout or optimize operation
"InvalidRequest"	Malformed API request	Check API payload format
"ConflictError"	Resource already exists	Use update instead of create
"QuotaExceeded"	Limit reached	Check subscription limits
"NetworkError"	Connectivity issues	Verify network configuration

Troubleshooting Guide

Table of Contents

Quick Diagnostics

System Health Check

Portal Health Check

Component Status

Quick Fix Actions

Diagnostic Information Collection

System Information

Run in PowerShell

Portal Logs

Authentication Issues

Issue: Cannot Sign In to Portal

Symptoms

Solutions

Issue: "Insufficient Permissions" Error

Symptoms

Solutions

Check user's Azure AD roles

Check app permissions

Issue: Token Expiration

Symptoms

Solutions

Backup Failures

Issue: Backup Jobs Not Starting

Symptoms

Solutions

Check automation account status

Check runbook status

Check schedule

Link schedule to runbook

Issue: Backup Fails Mid-Execution

Symptoms

Common Error Messages and Solutions

Issue: Incomplete Backups

Symptoms

Solutions

Test specific API access

Test each endpoint

Portal Access Problems

Issue: Portal Won't Load

Symptoms

Solutions

Check App Service health

Restart App Service

Issue: Slow Portal Performance

Symptoms

Solutions

Scale up App Service Plan

Storage Issues

Issue: "Storage Full" Errors

Symptoms

Solutions

Get storage account usage

Set lifecycle management rules

Move blobs to archive tier

Issue: Storage Access Denied

Symptoms

Solutions

Allow Azure services

Regenerate and update keys

Update connection strings in App Service and Automation Account

Performance Problems

Issue: Slow Backup Performance

Symptoms

Solutions

Use batch operations where possible

Instead of individual calls, use:

Process policies in parallel

Compare with last backup

Only backup changed items

Drift Detection Issues

Issue: False Positive Drift Alerts

Symptoms

Solutions

Set new baseline after verified changes

Issue: Drift Not Being Detected

Symptoms

Solutions

Verify drift detection is enabled and scheduled