What causes DocumentClientException?

The ADF copy activity throughput exceeds the RU/s provisioned on the target Cosmos DB container or database. Too many parallel copy workers or a high degree of write parallelism configured in the copy activity. Cosmos DB is using shared throughput at the database level and other collections are consuming the available RUs simultaneously. Large document sizes or complex indexing policies increase RU consumption per write beyond expected levels

How do I fix DocumentClientException?

Step 1: In the ADF copy activity settings, reduce the 'Write batch size' and 'Degree of copy parallelism' to lower the write throughput and RU consumption.. Step 2: Temporarily increase the provisioned RU/s on the target Cosmos DB container or database in the Azure portal to accommodate the copy activity's peak throughput.. Step 3: Consider enabling autoscale on the Cosmos DB container so it can automatically scale RUs during high-throughput copy operations without manual intervention.. Step 4: Review the Cosmos DB indexing policy and exclude paths that are not needed for queries — reducing the number of indexed paths lowers RU cost per write.. Step 5: Schedule large ADF copy jobs during off-peak hours when other workloads are not competing for the same provisioned RUs.

High severitycapacityAzure Data Factory →

Power BI Refresh Error:
DocumentClientException

What does this error mean?

A DocumentClientException with the message 'Request rate is large' occurs when ADF's copy activity exceeds the provisioned Request Units (RUs) on an Azure Cosmos DB container, causing the Cosmos DB service to throttle write or read operations.

Common causes

1The ADF copy activity throughput exceeds the RU/s provisioned on the target Cosmos DB container or database
2Too many parallel copy workers or a high degree of write parallelism configured in the copy activity
3Cosmos DB is using shared throughput at the database level and other collections are consuming the available RUs simultaneously
4Large document sizes or complex indexing policies increase RU consumption per write beyond expected levels

How to fix it

1Step 1: In the ADF copy activity settings, reduce the 'Write batch size' and 'Degree of copy parallelism' to lower the write throughput and RU consumption.
2Step 2: Temporarily increase the provisioned RU/s on the target Cosmos DB container or database in the Azure portal to accommodate the copy activity's peak throughput.
3Step 3: Consider enabling autoscale on the Cosmos DB container so it can automatically scale RUs during high-throughput copy operations without manual intervention.
4Step 4: Review the Cosmos DB indexing policy and exclude paths that are not needed for queries — reducing the number of indexed paths lowers RU cost per write.
5Step 5: Schedule large ADF copy jobs during off-peak hours when other workloads are not competing for the same provisioned RUs.

Frequently asked questions

Does ADF automatically retry on Cosmos DB throttling errors?

Yes — ADF has built-in retry logic for transient Cosmos DB throttling (HTTP 429), but if the RU deficit is large and sustained, retries will eventually be exhausted and the activity will fail with DocumentClientException.

Should I use 'Upsert' or 'Insert' write behavior when copying to Cosmos DB to reduce RU usage?

Insert is generally more RU-efficient than Upsert for net-new data because Upsert requires a read-before-write lookup; use Insert when you are certain there are no duplicate documents, and Upsert only when idempotency is required.