Troubleshooting Guide¶

Azure Authentication Issues¶

"Failed to authenticate with Azure"¶

Symptoms:

• Key Vault scans fail immediately
• "No Azure credentials available" error

Causes & Solutions:

1. Managed Identity not enabled

   # Verify managed identity is assigned
   az vm show --name <vm-name> --resource-group <rg> --query identity
   

   Fix: Enable system-assigned or user-assigned managed identity

2. Service Principal credentials expired

   # Check credential expiry
   az ad sp credential list --id <app-id>
   

   Fix: Rotate service principal secret

3. Wrong environment variables

4. Check AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID

5. Verify AZURE_USE_MANAGED_IDENTITY=true if using managed identity

6. Network connectivity

7. Ensure outbound access to login.microsoftonline.com
8. Check NSG/firewall rules

Key Vault Access Issues¶

"Access denied" or "Forbidden" for Key Vault¶

Symptoms:

• Some vaults show errors in scan results
• "AuthorizationPermissionDenied" error

Solutions:

1. Run the setup script

   ./setup-certifyclouds-access.sh --principal-id $PRINCIPAL_ID --apply
   

2. Check RBAC vs Access Policies

3. Some vaults use RBAC, others use Access Policies

4. The setup script handles both

5. Verify role assignments

   az role assignment list --assignee $PRINCIPAL_ID --all
   

"Network unreachable" for Key Vault¶

Symptoms:

• Vaults with firewall enabled fail
• Timeout errors during scan

Solutions:

1. Add subnet to firewall

   az keyvault network-rule add \
     --name <vault-name> \
     --subnet /subscriptions/.../subnets/<subnet>
   

2. Use Private Endpoints

3. Configure private endpoints for Key Vault

4. Update DNS resolution

5. Check service endpoints

6. Ensure Microsoft.KeyVault service endpoint is enabled on subnet

Licence Issues¶

"Licence validation failed"¶

Symptoms:

• A full-page screen reads "Licence could not be validated", "No licence key configured" or "Can't reach the licence server"
• API returns 403 with licence error

Solutions:

1. Verify licence key

   echo $CERTIFYCLOUDS_LICENSE_KEY
   

2. Should be in format CC-XXXXXXXX-XXXXXXXX-XXXXXXXX

3. Check network access

   curl https://license.certifyclouds.com/health
   

4. Should return HTTP 200

5. Check licence expiry

   curl http://localhost:8080/api/system/license/status
   

"Your licence has expired"¶

Solutions:

1. Contact [email protected] to renew
2. Receive new licence key
3. Update CERTIFYCLOUDS_LICENSE_KEY environment variable
4. Restart the application

Database Issues¶

"Cannot connect to database"¶

Symptoms:

• Application fails to start
• "Connection refused" errors

Solutions:

1. Verify PostgreSQL is running

   az postgres flexible-server show --name <server> --resource-group <rg>
   

2. Check connection string

   echo $DATABASE_URL
   # Format: postgresql://<user>:<password>@<host>:5432/<dbname>
   

3. Test connectivity

4. Confirm the database host is reachable from the container subnet

5. Check firewall and VNet rules allow the connection

6. Check firewall rules

7. For Azure PostgreSQL, ensure VNet integration or public access

"Database migration failed"¶

Solutions:

1. Check application logs for specific error
2. Ensure database user has CREATE/ALTER permissions
3. Contact support with migration error details

Performance Issues¶

Scans are slow¶

Symptoms:

• Scans take >10 minutes
• Timeout errors

Solutions:

1. Reduce concurrent workers

   DISCOVERY_MAX_WORKERS=3  # Reduce from default 5
   

2. Use quick scans

3. Run Scan reads every vault

4. Quick scan (menu next to Run Scan) skips vaults read within the scan cache lifetime

5. Filter subscriptions

6. Scan only needed subscriptions

7. Select just those subscriptions in Settings → Subscriptions and click Save Selection

8. Check rate limiting

9. Azure ARM has rate limits
10. Reduce workers if hitting 429 errors

Application is slow¶

Solutions:

1. Increase container resources
2. Minimum: 1 vCPU, 2GB RAM

3. Recommended: 2 vCPU, 4GB RAM

4. Check database performance

5. Upgrade PostgreSQL tier if needed

6. Review slow query logs

7. Check caching is on

8. In Settings → Advanced → App behaviour, Cache rotation matches and Faster repeat scans are on by default

Rotation Issues (PRO + ENTERPRISE)¶

"No matches found" for rotation¶

Symptoms:

• App Registrations discovered but no Key Vault matches

Solutions:

1. Enable hint caching

2. Improves matching accuracy

3. Add tags to secrets

   az keyvault secret set-attributes \
     --vault-name <vault> \
     --name <secret> \
     --tags app-id=<app-id>
   

4. Use consistent naming

5. Name secrets similarly to App Registration

"Rotation failed - permission denied"¶

Solutions:

1. Grant Graph API permissions

   az ad app permission add \
     --id $CLIENT_ID \
     --api 00000003-0000-0000-c000-000000000000 \
     --api-permissions 1bfefb4e-e0b5-418b-a88f-73c46d2cc8e9=Role
   
   az ad app permission admin-consent --id $CLIENT_ID
   

2. Grant Key Vault write permissions

   az role assignment create \
     --assignee $PRINCIPAL_ID \
     --role "Key Vault Secrets Officer" \
     --scope /subscriptions/<sub-id>
   

Sync Issues (PRO + ENTERPRISE)¶

"AWS credentials invalid"¶

Solutions:

1. Verify access key/secret in AWS IAM console
2. Create new access key if needed
3. Check IAM policy allows required operations

"Sync timeout"¶

Solutions:

1. Check network connectivity to AWS/GCP
2. Reduce concurrent sync operations
3. Verify endpoint URLs are correct

Alert Issues¶

Emails not received¶

Solutions:

1. Check the active provider in Settings → Advanced → Email

2. Send a test email from the same page and review the displayed result

3. Check spam/junk folder

4. Review application logs for email errors

Webhooks not delivered¶

Solutions:

1. Verify webhook URL
2. Test URL is accessible from container

3. Check for typos

4. Test endpoint manually

   curl -X POST <webhook-url> \
     -H "Content-Type: application/json" \
     -d '{"test": true}'
   

5. Check firewall rules

6. Ensure outbound HTTPS is allowed

Sign-in Issues¶

"Account locked"¶

Solutions:

1. Wait for automatic unlock: accounts unlock automatically after the configured lockout period

2. Admin unlock

3. Another admin can unlock via Settings > Users

4. Contact support if no other admin account is available, we can guide you through account recovery

"Invalid credentials" but password is correct¶

Solutions:

1. Check username is correct (case-sensitive)
2. Verify SSO isn't overriding local auth
3. Reset password if needed

Container Issues¶

Container crashes on startup¶

Solutions:

1. Check logs

   docker logs certifyclouds-app
   az containerapp logs show --name <app> --resource-group <rg>
   

2. Verify environment variables

3. Required: DATABASE_URL, CERTIFYCLOUDS_LICENSE_KEY

4. Check resource limits

5. Ensure sufficient CPU/memory

"Exit code 255" on ACI¶

Cause: Bash entrypoint script issues in ACI prevent the container from starting.

Solution: Ensure your container is using the official CertifyClouds image without a custom entrypoint wrapper. Contact support if this persists after using the provided deployment scripts.

Getting Help¶

If these solutions don't resolve your issue:

1. Collect information:
2. CertifyClouds version: curl http://localhost:8080/health
3. Error messages from logs

4. Steps to reproduce

5. Contact support:

6. Email: [email protected]

7. Include collected information

8. Response times:

9. STARTER: 4 UK business days
10. PRO: 2 UK business days
11. ENTERPRISE: Per signed support agreement