Diagnose and troubleshoot Azure Cosmos DB service unavailable exceptions
APPLIES TO: 
NoSQL
The SDK wasn't able to connect to Azure Cosmos DB. This scenario can be transient or permanent depending on the network conditions.
It's important to make sure the application design is following our guide for designing resilient applications with Azure Cosmos DB SDKs to make sure it correctly reacts to different network conditions. Your application should have retries in place for service unavailable errors.
When evaluating the case for service unavailable errors:
- What is the effect measured in volume of operations affected compared to the operations succeeding? Is it within the service SLAs?
- Is the P99 latency / availability affected?
- Are the failures affecting all your application instances or only a subset? When the issue is reduced to a subset of instances, it's commonly a problem related to those instances.
Troubleshooting steps
The following list contains known causes and solutions for service unavailable exceptions.
Verify the substatus code
In certain conditions, the HTTP 503 Service Unavailable error includes a substatus code that helps to identify the cause.
| Substatus Code | Description |
|---|---|
| 20001 | The service unavailable error happened because there are client side connectivity issues (failures attempting to connect). The client attempted to recover by retrying but all retries failed. |
| 20002 | The service unavailable error happened because there are client side timeouts. The client attempted to recover by retrying but all retries failed. |
| 20003 | The service unavailable error happened because there are underlying I/O errors related to the operating system. See the exception details for the related I/O error. |
| 20004 | The service unavailable error happened because client machine's CPU is overloaded. |
| 20005 | The service unavailable error happened because client machine's thread pool is starved. Verify any potential blocking async calls in your code. |
| 20006 | The connection between the service and client was interrupted or terminated in an unexpected manner. |
| >= 21001 | This service unavailable error happened due to a transient service condition. Verify the conditions in the above section, confirm if you have retry policies in place. If the volume of these errors is high compared with successes, reach out to Azure Support. |
The required ports are being blocked
Verify that all the required ports are enabled.
Client-side transient connectivity issues
Service unavailable exceptions can surface when there are transient connectivity problems that are causing timeouts and can be safely retried following the design recommendations.
Follow the request timeout troubleshooting steps to resolve it.
Service outage
Check the Azure status to see if there's an ongoing issue.
Next steps
- Diagnose and troubleshoot issues when you use the Azure Cosmos DB .NET SDK.
- Diagnose and troubleshoot issues when you use the Azure Cosmos DB Java SDK.
- Learn about performance guidelines for .NET.
- Learn about performance guidelines for Java.