Table of Contents

Troubleshooting

This guide helps you fix common issues when deploying XMPro on Azure.

Tip

Most issues are solved by:

  • Running az login to refresh your Azure authentication
  • Making sure you're in the right directory (terraform-xmpro-azure/examples/basic)
  • Using a different Azure region if you get "quota exceeded" errors

Most Common Issues

1. "Terraform command not found"

Solution:

# You haven't installed Terraform yet. Download it from:
# https://developer.hashicorp.com/terraform/install

# After installing, restart your terminal and try:
terraform version

2. "Error: building account... Please ensure you have logged in"

Solution:

# Login to Azure:
az login

# If that doesn't work, try:
az logout
az login --use-device-code

3. "Subscription not found" or wrong subscription

Solution:

# List your subscriptions:
az account list --output table

# Switch to the right one:
az account set --subscription "Your Subscription Name"

# Verify you're on the right subscription:
az account show

4. "Resource already exists" errors

Problem: Azure resource names must be globally unique.

Solution: Edit your terraform.tfvars and add a unique prefix:

prefix = "mycompany123"  # Add this line with a unique value

5. Deployment takes forever (more than 30 minutes)

Common causes:

  • Azure is slow in your region - this is normal for first deployment
  • Database creation can take 10-15 minutes alone

What to check:

  1. Look at the Azure Portal - are resources being created?
  2. Check terraform output - is it progressing?
  3. If stuck for over 45 minutes, try: 
    # Cancel with Ctrl+C, then:
terraform destroy  # Clean up partial deployment
terraform apply    # Try again

6. "Insufficient quota" or "SubscriptionIsOverQuotaForSku"

Problem: Your Azure subscription has limits on resources.

Quick Solution: Use smaller resource sizes in terraform.tfvars:

app_service_sku_name = "B1"  # Instead of B2
sql_sku_name = "Basic"        # Instead of S0

Long-term Solution: Request a quota increase in Azure Portal under "Quotas".

7. Login problems after deployment

Can't login with admin credentials?

Check your passwords in terraform.tfvars:

  • Must be at least 8 characters
  • Must have uppercase, lowercase, number, and special character
  • No spaces or quotes in the password

Forgot what you set? Look in your terraform.tfvars file for:

  • site_admin_password
  • company_admin_password

8. Applications won't start (App Service issues)

Quick fixes to try:

  1. Restart the services in Azure Portal:

    • Go to your resource group
    • Click on each App Service (SM, AD, DS)
    • Click "Restart"

  2. Check the logs in Azure Portal:

    • Go to your App Service
    • Click "Log stream" in the left menu
    • Look for error messages

  3. Wait a bit longer:

    • First startup can take 5-10 minutes
    • Check the /version endpoint: 
      curl "$(terraform output -raw sm_app_url)/version"

Getting More Help

Check Your Setup

Run this to verify everything is working:

# Check Terraform:
terraform version

# Check Azure login:
az account show

# Check your configuration:
terraform validate

Collect Information for Support

If you need to contact support, run:

# Save all outputs:
terraform output > terraform-outputs.txt

# Get resource group name:
terraform output resource_group_name

# List what was created:
az resource list --resource-group $(terraform output -raw resource_group_name) --output table

View Logs in Azure Portal

  1. Go to Azure Portal (portal.azure.com)
  2. Find your resource group (named like rg-yourcompany-dev-xmpro)
  3. Click on Application Insights resource
  4. Click "Logs" to see application logs
  5. Click "Failures" to see errors

Common Error Messages Explained

Error What it means Solution
"terraform: command not found" Terraform isn't installed Install Terraform
"Error: building account" Not logged into Azure Run az login
"SubscriptionIsOverQuotaForSku" Azure limits exceeded Use smaller SKUs or request quota increase
"Resource already exists" Name conflict Add unique prefix in terraform.tfvars
"Container image not found" Wrong version specified Use imageversion = "latest" in terraform.tfvars
"SSL/TLS connection error" Network/firewall issue Check corporate firewall or try different network

Still Stuck?

  1. Double-check the basics:

    • Are you in the right directory? (terraform-xmpro-azure/examples/basic)
    • Did you run terraform init first?
    • Is your terraform.tfvars file saved?

  2. Try a clean deployment:

    terraform destroy  # Remove everything
terraform apply    # Start fresh

  3. Use a different Azure region:

    # In terraform.tfvars, try:
location = "eastus2"  # or "westeurope", "southeastasia"

  4. Contact Support:

Note

For advanced troubleshooting and detailed technical issues, see the complete module documentation.

Last modified: October 06, 2025