Fix Azure Cosmos DB Errors: Auth, Queries & Setup Guide

Azure Cosmos DB fully supports Microsoft Entra ID (formerly Azure Active Directory) for both control-plane and data-plane authentication. If you're still using primary keys for production workloads, I'd strongly recommend migrating, but that transition is where most teams introduce auth errors.

First, confirm your Azure Cosmos DB account has local authentication methods enabled or disabled according to your policy. Some security teams disable primary key access entirely, which means your app must use Entra ID. Check this in the portal under your Cosmos DB account > Settings > Keys, you'll see whether "Disable local authentication" is toggled on.

For control-plane operations (creating databases, updating throughput, reading metadata), you use standard Azure RBAC built-in roles. The relevant built-in roles include "Cosmos DB Account Reader Role" for read-only access and "DocumentDB Account Contributor" for write access. Assign these at the subscription, resource group, or account scope depending on your security requirements.

For data-plane operations, running queries, inserting items, executing transactions, you need the Cosmos DB-specific native RBAC. The two built-in data-plane roles are:

• Cosmos DB Built-in Data Reader, read-only queries and item fetches
• Cosmos DB Built-in Data Contributor, full read/write/delete on items

You can also create custom roles with granular permissions. Once your role assignments are in place, update your application connection string to use the DefaultAzureCredential from the Azure Identity SDK rather than a primary key. In .NET, that looks like:

var client = new CosmosClient(
    accountEndpoint: "https://your-account.documents.azure.com:443/",
    tokenCredential: new DefaultAzureCredential()
);

If it worked, your application will connect without any key material. If it still fails with a 401 or 403, double-check that the role assignment scope matches the resource your app is accessing, scope mismatches are common and produce the same error code as a missing role assignment.

This step is for anyone hitting query failures, unexpected result sets, or "query is not supported" errors. The Azure Cosmos DB for NoSQL API uses a custom query language derived from SQL, but it's not T-SQL, and the differences trip people up constantly.

The NoSQL query language is a subset of standard SQL combined with NoSQL-specific extensions. It includes a rich set of hierarchical and relational operators, supports JavaScript-based user-defined functions (UDFs), and works against JSON documents modeled as trees with labeled nodes. JSON grammar is at the core of how Cosmos DB indexes and queries data.

Common query failures and their causes:

• "Query execution is not enabled on this endpoint", You're sending queries to the wrong endpoint. NoSQL queries must go to the document endpoint, not the Gremlin or Cassandra endpoint. Verify your connection string points to https://your-account.documents.azure.com:443/.
• Cross-partition query timeouts, If your query doesn't filter on the partition key, Cosmos DB fans out the query to every physical partition. On large containers this causes massive RU consumption and timeouts. Always include your partition key in the WHERE clause when you know it.
• Subquery not supported errors, Not all SQL subquery patterns are supported. The NoSQL query language includes a subset, not the full SQL Server subquery surface. Restructure as a correlated subquery using IN or ARRAY_CONTAINS where possible.
• UDF execution errors, JavaScript UDFs run in a sandboxed environment. They can't call external APIs or use Node.js modules. If your UDF is throwing, check that it's pure JavaScript computation only.

To test queries quickly without deploying code, use the Azure Portal's Data Explorer. Navigate to your Cosmos DB account > Data Explorer, select your container, click New SQL Query, and run queries interactively. The portal shows you RU charge per query, a critical metric for diagnosing performance problems.

SELECT c.id, c.name, c.status
FROM c
WHERE c.partitionKey = "region-us-east"
AND c.status = "active"
ORDER BY c.createdAt DESC
OFFSET 0 LIMIT 50

If the query returns results in the portal but fails in your application, the issue is almost certainly in how your SDK is constructing the query parameters, not the query itself.

I know this one is frustrating, especially when it happens intermittently under load. HTTP 412 is Azure Cosmos DB's way of telling you that an optimistic concurrency conflict has occurred, and your write was rejected because the item changed between the time you read it and the time you tried to write it.

Here's how the mechanism works: every item in Azure Cosmos DB for NoSQL has an _etag property. Every time that item is updated, the server assigns a new ETag value. When you read an item, the ETag comes back in the response headers. If you then send a write operation with an If-Match header containing the ETag you read, the server checks whether the item's current ETag matches. If another process updated the item in the meantime, the ETags won't match and you get HTTP 412.

This is intentional behavior, it prevents lost updates in concurrent systems. The fix is to implement a retry loop with re-fetch:

// C# example, retry on 412
async Task UpdateItemWithRetry(string id, string partitionKey)
{
    int maxRetries = 3;
    for (int i = 0; i < maxRetries; i++)
    {
        // Always re-read to get current ETag
        ItemResponse<MyItem> readResponse = await container.ReadItemAsync<MyItem>(
            id, new PartitionKey(partitionKey));

        MyItem item = readResponse.Resource;
        string currentEtag = readResponse.ETag;

        // Apply your changes
        item.Status = "updated";

        try
        {
            ItemRequestOptions options = new ItemRequestOptions
            {
                IfMatchEtag = currentEtag
            };
            await container.ReplaceItemAsync(item, id,
                new PartitionKey(partitionKey), options);
            return; // Success
        }
        catch (CosmosException ex) when (ex.StatusCode ==
            System.Net.HttpStatusCode.PreconditionFailed)
        {
            if (i == maxRetries - 1) throw;
            await Task.Delay(TimeSpan.FromMilliseconds(100 * (i + 1)));
        }
    }
}

If you're getting 412 errors consistently rather than intermittently, that suggests multiple application instances are writing to the same items at high frequency. Consider redesigning your write pattern to use the patch operation (PatchItemAsync) which supports atomic field-level updates and reduces the surface area for conflicts. The Cosmos DB SDK also supports If-None-Match headers for cache validation, use this when checking whether a resource needs to be re-fetched rather than always pulling the full item.

After implementing the retry, you should see 412 errors drop from your metrics. Monitor via Azure Monitor > Metrics > select your Cosmos DB account > filter by "Total Request Units" and "Http 4xx" to track the resolution.

Bulk insert failures are one of the most common Azure Cosmos DB pain points during initial data migration or during high-volume ingestion pipelines. You write a job that works beautifully against a 10,000-item test dataset, then run it against 10 million items and it either throttles out, times out, or starts silently dropping records.

The right approach depends on your SDK. For .NET, use the CosmosClient with bulk mode enabled, this is separate from the legacy bulk executor library. In the .NET SDK v3+, enabling bulk execution is a single flag at client construction time:

CosmosClientOptions options = new CosmosClientOptions
{
    AllowBulkExecution = true
};
CosmosClient client = new CosmosClient(connectionString, options);

With bulk execution enabled, the SDK batches your individual CreateItemAsync calls into groups automatically. This dramatically reduces the per-operation overhead and optimizes how your provisioned throughput is consumed.

For the Java SDK, the bulk API is exposed through the CosmosBulkOperations class. Both implementations optimize how throughput is consumed during large data loads.

For massive datasets, we're talking hundreds of millions of records, consider Apache Spark with the Azure Cosmos DB Spark connector. You can run bulk imports using Python or Scala against your existing Spark cluster, and the connector handles parallelism, partitioning, and retry logic for you.

Common bulk import errors and what they mean:

• 429 Too Many Requests, You've exhausted your provisioned Request Units. Temporarily increase your container's throughput before the migration, then scale it back down after. Navigate to your container > Scale & Settings > adjust the RU/s slider.
• Request entity too large, Individual items exceed the 2MB document size limit. Split oversized documents before importing.
• Partition key not found, Your import data doesn't include the partition key field, or the field name doesn't match the container's partition key path exactly (it's case-sensitive).

Always run a small test batch of 1,000–5,000 items first, check the RU charge per item in Azure Monitor, and project your total RU cost before scaling up. This saves you from provisioning 50,000 RU/s for a migration that only needed 5,000.

A misconfigured API choice causes a specific class of Azure Cosmos DB problems that are hard to recognize because the connection often succeeds but behavior is wrong or features are missing. Getting the API selection right from the start, or migrating correctly when you're on the wrong one, matters more than most teams realize.

Azure Cosmos DB offers six API models, and choosing incorrectly is a very common setup mistake:

• NoSQL API, Best choice for greenfield applications. Uses native SQL queries with automatic indexing and schema flexibility for document workloads. This is the "native" Cosmos DB experience and has the deepest feature support, including vector search, change feed, and the most sophisticated RBAC implementation.
• MongoDB API, Choose this if you have an existing MongoDB application you want to migrate. Full wire protocol compatibility means most MongoDB drivers and tools work without code changes. Check the supported features and syntax list in the official docs before migrating, not every MongoDB operator is supported.
• Apache Cassandra API, For highly scalable workloads already using Cassandra Query Language. Wire protocol support means existing CQL-based applications migrate with minimal changes. Partitioning behavior differs slightly from native Cassandra so test your partition key strategies before production migration.
• Apache Gremlin API, For graph data. If your data has complex relationships that are expensive to query in a document model, Gremlin lets you traverse those relationships efficiently. Use graph data modeling guidance from the official docs to avoid common property-key mistakes.
• Table API, If you're migrating from Azure Table Storage and want premium capabilities like global distribution and automatic indexing without rewriting your application.
• PostgreSQL API, For distributed relational workloads where you need horizontal scaling but want to keep the PostgreSQL wire protocol. Connect using psql or any PostgreSQL client, then run SQL commands as normal.

Once you've created an Azure Cosmos DB account with a specific API, you cannot change it. If you realize you've chosen the wrong API, you need to create a new account and migrate your data. Plan your API choice carefully, evaluate your existing tooling, driver ecosystem, query patterns, and team familiarity before committing.

To confirm which API your existing account uses: Azure Portal > your Cosmos DB account > Overview. The API type appears prominently in the account details. If it says "Core (SQL)" that's the NoSQL API. If you're connecting with a MongoDB driver to a "Core (SQL)" account, nothing will work, that's a very common setup error.