Fix: Azure Cosmos DB Account Name Already Taken

Quick Answer

Cosmos DB account names are globally unique across all Azure tenants (they become DNS names). Choose a different name, import the existing account, or wait for a recently deleted account's name to be released.

The Error

Error: creating Cosmos DB Account "mydb-prod":
  The name 'mydb-prod' is not available. Please choose a different name.

What Causes This Error

1. Name Is Globally Taken

Cosmos DB accounts create a {name}.documents.azure.com DNS entry — the name must be unique across all of Azure, not just your subscription.

2. Soft-Deleted Account

Azure Cosmos DB supports soft delete. A recently deleted account with the same name may still be in recovery mode (up to 30 days).

3. Another Terraform Workspace

A different environment or team is already using this name in the same or different subscription.

How to Fix It

Solution 1: Use Unique Naming Convention

resource "random_id" "cosmos" {
  byte_length = 4
}
 
resource "azurerm_cosmosdb_account" "main" {
  name                = "myapp-${var.environment}-${random_id.cosmos.hex}"
  location            = azurerm_resource_group.main.location
  resource_group_name = azurerm_resource_group.main.name
  offer_type          = "Standard"
  kind                = "GlobalDocumentDB"
 
  consistency_policy {
    consistency_level = "Session"
  }
 
  geo_location {
    location          = azurerm_resource_group.main.location
    failover_priority = 0
  }
}

Solution 2: Import the Existing Account

# Check if the account exists in your subscription
az cosmosdb show --name mydb-prod --resource-group my-rg
 
# Import into Terraform
terraform import azurerm_cosmosdb_account.main \
  /subscriptions/SUB_ID/resourceGroups/my-rg/providers/Microsoft.DocumentDB/databaseAccounts/mydb-prod

Solution 3: Check DNS for Name Availability

# If the DNS resolves, the name is taken
nslookup mydb-prod.documents.azure.com
 
# Check via Azure CLI
az cosmosdb check-name-exists --name mydb-prod

Solution 4: Recover a Soft-Deleted Account

# List deleted accounts in your subscription
az cosmosdb restorable-database-account list --query "[?accountName=='mydb-prod']"
 
# If you own it, you can restore it instead of creating new

Troubleshooting Checklist

1. ✅ Is the name globally unique? (nslookup {name}.documents.azure.com)
2. ✅ Was the account recently deleted? (Soft delete may hold the name)
3. ✅ Does the account already exist in your subscription? (az cosmosdb show)
4. ✅ Can you add a random suffix to make the name unique?
5. ✅ Should you import the existing account instead?

Prevention Tips

• Include random suffixes or subscription-specific prefixes in Cosmos DB names
• Use random_id to generate unique suffixes automatically
• Check name availability before applying with az cosmosdb check-name-exists
• Tag accounts with ManagedBy = "terraform" for easy discovery

Related Articles

• All Troubleshooting Articles
• Terraform Glossary

Conclusion

Cosmos DB account names are globally unique DNS names. Use random suffixes in your naming convention, check availability before applying, and import existing accounts rather than trying to recreate them.