How to Resolve the GroupId SQL Is Not Supported Error

Issue

You receive the following error message:

Call to Microsoft.DocumentDB/databaseAccounts failed. Error message: GroupId sql is not supported\r\nActivityId: {activityIdentifier}, Microsoft.Azure.Documents.Common/2.14.0

Environment

• All database connectors
• Connection method: Private networking

Understanding the problem

The error GroupId SQL is not supported means you're using a group ID intended for a different database system.

Causes and solutions

Use the correct group ID that corresponds to the API type of your Azure Cosmos DB account.

Here are the correct groupIds for Azure Cosmos DB private endpoints:

• Sql: For Azure Cosmos DB accounts using the Core (SQL) API.
• MongoDB: For Azure Cosmos DB accounts using the MongoDB API.
• Cassandra: For Azure Cosmos DB accounts using the Cassandra API.
• Gremlin: For Azure Cosmos DB accounts using the Gremlin API.
• Table: For Azure Cosmos DB accounts using the Table API.
• MongoCluster: For Azure Cosmos DB for MongoDB vCore clusters.
• Analytical: For the Analytical Store of an Azure Cosmos DB account (if you're creating a private endpoint specifically for analytical workloads).

Resolution

When you are creating the private endpoint (either through the Azure portal, Azure CLI, or ARM template), ensure you select or specify the correct Target sub-resource (Group ID).

In the Azure Portal

1. Go to your Azure Cosmos DB account in the Azure portal.
2. Navigate to Settings > Networking.
3. Select the Private access tab.
4. Click + Private endpoint.
5. On the Basics tab, fill in your project details, name, and region.
6. Go to the Resource tab.
   • Select Connect to an Azure resource in my directory.
   • Select the subscription where your Cosmos DB account resides.
   • Your Resource type should automatically be Microsoft.DocumentDB/databaseAccounts.
   • Select your specific Azure Cosmos DB account from the dropdown.
   • From the dropdown, select the group ID that matches the API of your Cosmos DB account (e.g., Sql, MongoDB, Cassandra, Gremlin, Table, or Analytical if applicable).
     Do not select sql (lowercase) or anything that isn't one of these specific Cosmos DB group IDs.

7. Finalize the rest of the private endpoint creation process (Virtual Network, DNS, Tags, Review + create).

Using Azure CLI

When using az network private-endpoint create, make sure the --group-ids parameter matches your Cosmos DB account's API.

Example for a SQL (Core) API Cosmos DB account:

az network private-endpoint create \
    --name myCosmosDbPrivateEndpoint \
    --resource-group myResourceGroup \
    --vnet-name myVNet \
    --subnet mySubnet \
    --connection-name myConnection \
    --private-connection-resource-id "/subscriptions/<your-subscription-id>/resourceGroups/<your-cosmosdb-resource-group>/providers/Microsoft.DocumentDB/databaseAccounts/<your-cosmosdb-account-name>" \
    --group-ids "Sql" \ # <--- Make sure this is "Sql" (for Core API) or "MongoDB", "Cassandra", etc.
    --location <your-region> \
    --private-dns-zone "privatelink.documents.azure.com" # Or relevant DNS zone for your API