Skip to content

Troubleshooting Guide

Azure Authentication Issues

Azure authentication fails

Symptoms:

  • Key Vault scans fail immediately
  • Authentication error in application logs

Causes & Solutions:

  1. Managed Identity not enabled

    # Verify managed identity is assigned
    az containerapp identity show --name <app> --resource-group <rg>
    
    Fix: Assign the user-assigned managed identity to your Container App or Container Instance

  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

Key Vault access is denied

Symptoms:

  • Some vaults show errors in scan results
  • Permission error in scan results

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
    

Key Vault cannot be reached

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 cannot be validated

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 in Settings > Licence. It should have the format CC-XXXXXXXX-XXXXXXXX-XXXXXXXX.

  2. Check network access

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

  3. Should return HTTP 200

  4. Check licence expiry in Settings > Licence.

Licence has expired

Solutions:

  1. Contact sales@certifyclouds.com to renew
  2. Receive new licence key
  3. Enter the new key in Settings > Licence

Database Issues

Database connection fails

Symptoms:

  • Application fails to start
  • Database connection errors in application logs

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, check the private subnet and network rules

Database migration fails

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. Speeds up repeated matching

  3. Add tags to secrets

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

  4. Use consistent naming

  5. Name secrets similarly to App Registration

Rotation permission is denied

Solutions:

  1. Grant Graph API permissions

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

  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 fail

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 times out

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 is 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. Recover access with Forgot your password? on the sign-in page and your recovery secret

"Invalid username or password" 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. Check DATABASE_URL and the required SECRET_KEY; a missing licence key blocks access after startup

  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: check /api/system/version from your deployment
  3. Error messages from logs
  4. Steps to reproduce

  5. Contact support:

  6. Email: support@certifyclouds.com
  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