Troubleshooting

Common issues encountered when deploying and operating VaultGuard360, organized by symptom with cause and fix.

Dashboard Issues

White Screen After Deployment

Diagnosis:

curl -s https://<func>.azurewebsites.net/assets/index-*.js \
  -o /dev/null -w "%{content_type}"
# Expected: application/javascript
# Broken:   text/html

Fix:

1. Verify the www/assets/ directory is included in the deployment ZIP
2. Ensure the ServeSPAFallback handler resolves the static file before falling back to index.html
3. Redeploy the Function App with a fresh ZIP package

Dashboard Shows Loading Spinner Indefinitely

Cause 1: Cold start

# Warm up the Function App first
curl https://<func>.azurewebsites.net/api/health
# Wait for a 200 response, then reload the dashboard

For production workloads on an App Service Plan (not Consumption), enable Always On to prevent cold starts.

Cause 2: License endpoint failing

1. Open browser DevTools → Network tab
2. Look for the /api/license request
3. If it returns an error, check that the TIER app setting is configured correctly

# Check current TIER setting
az functionapp config appsettings list \
  --name <func> --resource-group <rg> \
  --query "[?name=='TIER'].value" -o tsv
# Valid values: trial, professional, enterprise (case-insensitive)

Wrong Tier Displayed

# Set the correct tier
az functionapp config appsettings set \
  --name <func> --resource-group <rg> \
  --settings TIER=professional

Identity and Authentication Issues

"DefaultAzureCredential failed"

# Verify AZURE_CLIENT_ID is set
az functionapp config appsettings list \
  --name <func> --resource-group <rg> \
  --query "[?name=='AZURE_CLIENT_ID'].value" -o tsv

# Verify the identity is attached to the Function App
az functionapp identity show --name <func> --resource-group <rg>

Ensure AZURE_CLIENT_ID matches the clientId of the user-assigned identity, not the principalId.

"Access Denied" on Key Vault Operations

Fix — Step 1: Verify the role assignment exists:

PRINCIPAL_ID=$(az identity show \
  --name id-vaultguard360 --resource-group <rg> \
  --query principalId -o tsv)

az role assignment list \
  --assignee $PRINCIPAL_ID \
  --scope /subscriptions/<sub-id> -o table

Fix — Step 2: Verify RBAC authorization is enabled on the Key Vault:

az keyvault show --name <vault> \
  --query properties.enableRbacAuthorization
# Must return: true

Fix — Step 3: If the role was recently assigned, wait 5–10 minutes for propagation and retry.

Permission Status Shows Missing Roles

curl https://<func>.azurewebsites.net/api/permission-status

This returns each subscription with hasKeyVaultAccess boolean flags. Assign the Key Vault Reader role on any subscription showing false and wait 5–10 minutes for propagation.

Email and Notification Issues

ACS Email Not Delivering

Fix — Step 1: Verify the ACS connection string is set:

az functionapp config appsettings list \
  --name <func> --resource-group <rg> \
  --query "[?name=='ACS_CONNECTION_STRING'].value" -o tsv
# Should return: endpoint=https://acs-<name>.<region>.communication.azure.com/;accesskey=...

If ACS_CONNECTION_STRING is missing, retrieve and set it manually:

az communication list-key --name <acs-name> --resource-group <rg>
# Copy primaryConnectionString

az functionapp config appsettings set \
  --name <func> --resource-group <rg> \
  --settings "ACS_CONNECTION_STRING=<primaryConnectionString>"

Fix — Step 2: Check Application Insights for ACS errors:

az monitor app-insights query \
  --app <app-insights-name> --resource-group <rg> \
  --analytics-query "traces | where message contains 'ACS' or message contains 'email' | order by timestamp desc | take 20"

SMTP Not Delivering

Common fixes:

• Office 365: Use smtp.office365.com:587 with TLS enabled
• Gmail: Use smtp.gmail.com:587 — regular passwords don't work; generate an App Password at https://myaccount.google.com/apppasswords
• From address mismatch: Many SMTP servers reject emails where the From address differs from the authenticated account

# Check SMTP config via the API
curl https://<func>.azurewebsites.net/api/smtp-config

Teams Webhook Not Delivering

Fix — Step 1: Verify the webhook URL format. Valid patterns:

• https://<tenant>.webhook.office.com/webhookb2/...
• https://outlook.office.com/webhook/...

Fix — Step 2: Verify webhooks are available on your tier:

curl https://<func>.azurewebsites.net/api/license | python3 -m json.tool
# webhookEnabled should be true

Fix — Step 3: Test the webhook URL directly:

curl -H "Content-Type: application/json" \
  -d '{"text":"VaultGuard360 test message"}' \
  "<your-webhook-url>"

Scan Issues

Scans Show 0 Vaults or 0 Items

# Check which subscriptions are accessible
curl https://<func>.azurewebsites.net/api/permission-status

• If totalAccessible is 0, the managed identity has no Key Vault Reader role on any subscription
• If subscriptions appear but hasKeyVaultAccess is false, assign the Key Vault Reader role at subscription scope

Scan Timeout

Mitigations:

• Use team routing to focus monitoring on specific subscriptions rather than all subscriptions in a single pass
• Check Application Insights for timeout errors to identify which subscriptions are slow
• For Enterprise: consider splitting monitoring across multiple Function App instances if needed

Deployment Issues

ZIP Deploy Fails

Fix — Step 1: Ensure these app settings disable server-side build:

az functionapp config appsettings set \
  --name <func> --resource-group <rg> \
  --settings SCM_DO_BUILD_DURING_DEPLOYMENT=false ENABLE_ORYX_BUILD=false

Fix — Step 2: Verify Python packages were installed for the correct Linux platform:

pip install --target=".python_packages/lib/site-packages" \
  --platform manylinux2014_x86_64 \
  --only-binary=:all: \
  --implementation cp \
  --python-version 3.11 \
  -r requirements.txt

Warning: Do not set WEBSITE_RUN_FROM_PACKAGE=1. Standard ZIP deploy works without this setting, and enabling it can cause file access issues.

Diagnostic Commands

Run these commands to quickly gather diagnostic information:

# Health check (includes tier and identity info)
curl https://<func>.azurewebsites.net/api/health

# Permission status (RBAC check per subscription)
curl https://<func>.azurewebsites.net/api/permission-status

# License/tier check
curl https://<func>.azurewebsites.net/api/license

# Verify SPA assets serve correctly (should return application/javascript)
curl -s https://<func>.azurewebsites.net/assets/index-*.js \
  -o /dev/null -w "%{content_type}"

# Check all app settings
az functionapp config appsettings list \
  --name <func> --resource-group <rg> -o table

# Check managed identity attachment
az functionapp identity show --name <func> --resource-group <rg>

# View recent logs in Application Insights
az monitor app-insights query \
  --app <app-insights-name> --resource-group <rg> \
  --analytics-query "traces | order by timestamp desc | take 50"

# Restart the Function App
az functionapp restart --name <func> --resource-group <rg>

Getting Support

If these steps do not resolve your issue, contact support@sentinelvaultsystems.com with:

• Your subscription ID
• The Function App name and resource group
• Output from /api/health and /api/permission-status
• Relevant Application Insights error traces