Azure Cosmos DB Troubleshooting: Fix Every Common Error

Good Azure Cosmos DB troubleshooting starts with data, not guesswork. The metrics blade is your ground truth. Open the Azure Portal, navigate to your Cosmos DB account, and go to Monitoring > Metrics in the left navigation pane.

Create a custom chart with the following metrics pinned side by side:

• Total Requests split by StatusCode, immediately shows you the ratio of 200 (success) vs 429 (throttled) vs 408 (timeout) responses
• Normalized RU Consumption split by CollectionName and Region
• Physical Partition Throughput (under the "Throughput" namespace), shows hot partition skew
• Data & Index Storage, useful if you suspect an indexing explosion

If you're running Azure Diagnostics, you can also query the CDBDataPlaneRequests log table in Log Analytics. This query isolates every throttled request with its partition key:

CDBDataPlaneRequests
| where TimeGenerated > ago(1h)
| where statusCode == 429
| summarize ThrottledCount = count() by partitionKey, collectionName, bin(TimeGenerated, 5m)
| order by ThrottledCount desc

This single query has saved me hours on complex deployments. You'll see exactly which partition keys are generating throttles, which tells you whether you have a hot partition problem or a global throughput sizing issue.

If you see event ID 40501 in the response body of a 429, that's the Cosmos DB internal code for "collection throughput limit exceeded." If you see 40613, that means the database is temporarily unavailable, usually due to a planned maintenance event or regional failover.

What success looks like: Your 429 rate drops to zero, Normalized RU Consumption stays below 70% across all partition key ranges, and latency holds steady under 10ms for point reads.

Azure Cosmos DB 429 throttling is the single most common error I deal with, and it almost always has one of three causes: you're under-provisioned, you have a hot partition, or a burst of traffic is outpacing your autoscale configuration. Let's address each.

If you're under-provisioned globally: Go to your container in the Portal, click Settings > Scale & Settings, and increase the Manual throughput RU/s value. A good starting formula for a production read-heavy workload is: (average item size in KB × reads per second × replication factor) / 1 RU. For a 5KB item read at 500 RPS with 3 replicas, you need roughly 7,500 RU/s as a floor.

If autoscale is enabled but still throttling: Check whether your max RU/s ceiling is too low. Cosmos DB autoscale scales between 10% and 100% of your configured maximum. If your max is set to 4,000 RU/s, the minimum floor is 400 RU/s, and if traffic spikes before autoscale can catch up (it typically responds within seconds, not milliseconds), you'll get a burst of 429s. Consider switching to manual provisioned throughput if your workload is predictable, or raise your autoscale max.

If it's a hot partition: Increasing RU/s won't fully help because Cosmos DB distributes throughput evenly across physical partitions. A single hot logical partition is limited to its physical partition's share. The real fix is redesigning your partition key, see Step 4. As a short-term band-aid, you can enable Burst Capacity (in Preview as of early 2026) which allows partitions to consume unused RU budget from other partitions temporarily.

Also check whether your SDK is implementing exponential backoff on 429 responses. The RetryAfterInMilliseconds field in the 429 response header tells your client exactly how long to wait before retrying. If your code is ignoring this and retrying immediately, you're amplifying the problem.

What success looks like: The 429 count in your metrics drops to near zero. Server-side latency returns to single-digit milliseconds for point reads.

If your Cosmos DB metrics show healthy RU consumption and low latency but your application is still throwing timeout errors, the SDK configuration is almost always responsible. This is one of those Azure Cosmos DB troubleshooting scenarios that's particularly nasty because the database itself is perfectly fine, the problem lives entirely in your application layer.

For the .NET SDK v3, here's a properly tuned client initialization:

CosmosClientOptions options = new CosmosClientOptions
{
    ConnectionMode = ConnectionMode.Direct,
    RequestTimeout = TimeSpan.FromSeconds(10),
    OpenTcpConnectionTimeout = TimeSpan.FromSeconds(5),
    MaxRetryAttemptsOnRateLimitedRequests = 9,
    MaxRetryWaitTimeOnRateLimitedRequests = TimeSpan.FromSeconds(30),
    ApplicationPreferredRegions = new List<string>
    {
        "East US",
        "West US 2"
    }
};
CosmosClient client = new CosmosClient(connectionString, options);

Pay close attention to ConnectionMode.Direct. This uses the TCP protocol to connect directly to Cosmos DB backend nodes instead of routing through the Gateway. For applications running inside Azure (App Service, AKS, VMs), Direct mode reduces latency significantly. For on-premises apps or apps behind strict firewalls, stick with ConnectionMode.Gateway, Direct mode requires outbound TCP access on ports 10000–20000.

For Java SDK v4, the equivalent configuration looks like this:

CosmosClientBuilder builder = new CosmosClientBuilder()
    .endpoint(endpoint)
    .key(key)
    .directMode(DirectConnectionConfig.getDefaultConfig())
    .throttlingRetryOptions(new ThrottlingRetryOptions()
        .setMaxRetryAttemptsOnThrottledRequests(9)
        .setMaxRetryWaitTime(Duration.ofSeconds(30)));
CosmosAsyncClient client = builder.buildAsyncClient();

One thing I see constantly: teams using a single CosmosClient instance per request. Don't do this. CosmosClient is expensive to initialize, it opens and maintains a connection pool. Instantiate it once at application startup and treat it as a singleton for the lifetime of your process. In .NET, register it as a singleton in your DI container.

If you're seeing HTTP 408 (Request Timeout) specifically, and the Portal shows server-side latency is fine, the timeout is occurring on the client side before the server even responds. Increase RequestTimeout as a temporary measure, then investigate whether your query is simply returning too much data.

What success looks like: Your application logs stop showing timeout exceptions. P99 latency as measured by your APM tool aligns with the server-side latency shown in the Cosmos DB Portal metrics.

This is the step most teams skip, and it's the one that causes the most long-term pain. Azure Cosmos DB partition key design is not just a performance concern, a bad partition key creates structural throttling that no amount of RU/s increase will fully resolve. I've watched teams throw money at this problem for months before finally biting the bullet and redesigning.

A hot partition forms when a disproportionate number of requests target a single logical partition. Common examples:

• Using userId as a partition key when you have a handful of "power users" generating 90% of activity
• Using date or timestamp as a partition key, all writes always go to "today"
• Using a boolean or low-cardinality field like isActive or country when most documents are from the same country

The diagnostic test: in Log Analytics, run this query to calculate partition key distribution:

CDBPartitionKeyStatistics
| where TimeGenerated > ago(1h)
| where CollectionName == "your-container-name"
| project PartitionKey, SizeKb
| order by SizeKb desc
| take 20

If the top 5 partition keys account for more than 50% of total storage, you have a skew problem.

Synthetic partition key approach: If you can't change your data model, append a random suffix to your existing partition key to spread load. For example, instead of /userId, use /userId_suffix where suffix is a random number between 0 and 9. You then write to 10 logical partitions per user and fan out reads across all 10, a common pattern called partition key suffixing.

// Write: append suffix 0-9 randomly
string partitionKey = $"{userId}_{random.Next(0, 10)}";

// Read: fan-out query across all suffixes
var tasks = Enumerable.Range(0, 10).Select(suffix =>
    container.ReadItemAsync<MyItem>(id, new PartitionKey($"{userId}_{suffix}"))
);

For new containers, consider a hierarchical partition key (available in Cosmos DB for NoSQL). This lets you specify two levels, for example, /tenantId as the first level and /userId as the second. It gives you logical grouping without sacrificing distribution.

What success looks like: The Physical Partition Throughput metric shows balanced consumption across all partition key ranges, no single range consistently above 60–70% while others are under 20%.

Azure Cosmos DB indexes every property on every document by default. That sounds helpful, but on write-heavy workloads or documents with large, deeply nested schemas, the default indexing policy becomes a silent RU drain. Every write has to update the index for every indexed path, and if you have 50 properties per document, that's 50 index updates on each insert or update.

Go to your container in the Portal and click Settings > Indexing Policy. You'll see JSON that looks something like this for the default policy:

{
    "indexingMode": "consistent",
    "automatic": true,
    "includedPaths": [
        {
            "path": "/*"
        }
    ],
    "excludedPaths": [
        {
            "path": "/\"_etag\"/?"
        }
    ]
}

The /* wildcard is the culprit. For a write-heavy workload, switch to an opt-in model where you only index the paths you actually query on:

{
    "indexingMode": "consistent",
    "automatic": true,
    "includedPaths": [
        { "path": "/userId/?" },
        { "path": "/status/?" },
        { "path": "/createdAt/?" }
    ],
    "excludedPaths": [
        { "path": "/*" }
    ]
}

This can reduce write RU cost by 40–60% on complex document schemas. I've seen this single change drop a team's monthly Cosmos DB bill by thousands of dollars.

For slow query performance specifically, you may need to add a composite index. If you're running a query like SELECT * FROM c WHERE c.status = 'active' ORDER BY c.createdAt DESC, Cosmos DB can't use single-property indexes for this, it needs a composite index on (status, createdAt):

{
    "compositeIndexes": [
        [
            { "path": "/status", "order": "ascending" },
            { "path": "/createdAt", "order": "descending" }
        ]
    ]
}

Without this composite index, Cosmos DB performs a full cross-partition scan to satisfy the ORDER BY, which is both slow and RU-expensive. Adding it drops query cost from thousands of RUs to tens of RUs on the same dataset.

Also check: if indexingMode is set to "none", only point reads by document ID are possible. All queries will fail with a 400 error unless you pass the partition key explicitly. This sometimes happens after a misconfigured ARM template deployment.

What success looks like: Write RU cost per document drops noticeably in your metrics. Slow queries that previously showed 10,000+ RU charges in the Query Stats pane now run in under 100 RUs. The query execution time drops from seconds to milliseconds.