Copy Merchant Data, Error: Failure happened on 'Sink' side. ErrorCode=UserErrorDocumentDBWriteError,'Type=Microsoft.DataTransfer.Common.Shared.HybridDeliveryException,Message=Documents failed to import. Error message:Missing partition key header for point

Question

Copy Merchant Data, Error: Failure happened on 'Sink' side. ErrorCode=UserErrorDocumentDBWriteError,'Type=Microsoft.DataTransfer.Common.Shared.HybridDeliveryException,Message=Documents failed to import. Error message:Missing partition key header for point

Venkat Pendyala - Azure 5

Operation on target ForEach failed: Activity failed because an inner activity failed; Inner activity name: Copy Merchant Data, Error: Failure happened on 'Sink' side. ErrorCode=UserErrorDocumentDBWriteError,'Type=Microsoft.DataTransfer.Common.Shared.HybridDeliveryException,Message=Documents failed to import. Error message:Missing partition key header for point operation

ActivityId: 9aa439d6-dadc-4e61-b423-779167166aba, Windows/10.0.20348 cosmos-netstandard-sdk/3.18.0, documentdb-dotnet-sdk/2.5.1 Host/64-bit MicrosoftWindowsNT/6.2.9200.0.,Source=Microsoft.DataTransfer.DocumentDbManagement,''Type=Microsoft.Azure.Documents.DocumentClientException,Message=Missing partition key header for point operation

ActivityId: 9aa439d6-dadc-4e61-b423-779167166aba, Windows/10.0.20348 cosmos-netstandard-sdk/3.18.0, documentdb-dotnet-sdk/2.5.1 Host/64-bit MicrosoftWindowsNT/6.2.9200.0,Source=Microsoft.Azure.Documents.Client,'

Venkat Pendyala - Azure 5 Reputation points

2026-03-16T07:23:27.2533333+00:00

The file seems to be processed sometime but often fails with the above exception. The partition key always exists in the file.

1 answer

Your answer

Venkat Pendyala - Azure 5 Reputation points

2026-03-16T07:23:27.2533333+00:00

The file seems to be processed sometime but often fails with the above exception. The partition key always exists in the file.

Answer 1

Smaran Thoomu 34,155 Microsoft External Staff Moderator

@Venkat Pendyala - Azure Hey Venkat, this “Missing partition key header for point operation” means that when ADF’s Copy activity is writing to Cosmos DB it isn’t sending the required partition-key header in the request. Even if your source JSON has the key field, ADF needs to know which property to use so it can populate that header on each write.

Here’s what to check and update:

Validate your Cosmos container’s partition-key path • In the Azure portal, go to your Cosmos DB account → Data Explorer → select your database/container → Settings → “Partition key” • Note the exact path (e.g. /customerId, /region), including the leading slash and correct casing.
Configure the partition key in your ADF sink dataset • Edit the Cosmos DB (DocumentDB) dataset you’re using as the sink. • Under Connection → DocumentDB partition key, enter the same path you saw in the portal (e.g. /customerId).
Map the source field to that partition key • In your Copy activity’s Sink tab → Mapping, ensure the column in your source that holds the partition-key value maps to the partition-key property in Cosmos. • If you don’t explicitly map, ADF assumes your JSON has the field, but you still must define the path in the dataset.
Enable Upsert (optional but often helpful) • Still in the Sink tab, toggle “Enable upsert.” • Upsert operations still require the partition-key header, but this setting can reduce failures when items already exist.
Double-check your data • Make sure every row/document in your source has a non-null, non-empty value in that partition-key field. Any missing value will trigger the same error.

After you’re sure the path in the dataset matches your container and the mapping is correct, run the pipeline again.

—Cheers,

Your Azure Support Team

References

Copy data to Azure Cosmos DB with Azure Data Factory https://docs.microsoft.com/azure/data-factory/connector-azure-cosmos-db
Partition key design for Azure Cosmos DB https://docs.microsoft.com/azure/cosmos-db/partitioning-overview
Troubleshoot Common Azure Data Factory copy activity errors https://docs.microsoft.com/azure/data-factory/copy-activity-error-codes

—

If you still see the error, can you share:

The exact partition-key path your Cosmos container uses?
A snippet of your sink dataset JSON showing the “documentDBPartitionKey” setting?
A sample source record (with the PK field) that’s failing?

This will help us pinpoint what’s missing.

Note: This content was drafted with the help of an AI system. Please verify the information before relying on it for decision-making.

YUZUKI AYASE 116 Reputation points

2026-03-18T04:32:36.1433333+00:00
Hello,

We are currently experiencing an issue with our Azure Data Factory (ADF) Copy Activity when restoring data to Azure Cosmos DB.

The error we are receiving is:

Missing partition key header for point operation

What is unusual is that:

The pipeline configuration has not been changed

The Cosmos DB container schema (including partition key) remains unchanged

The source data is identical (we are reusing previously successful backup data)

The same process was working successfully about one week ago

However, we are now seeing partial failures, where some documents are written successfully while others fail with the above error.

Based on our investigation, it appears that the write behavior may have changed internally (e.g., from bulk execution to point operations), resulting in stricter partition key handling.

We have already tried all recommended approaches, including:

Explicit field mapping for the partition key

Verifying partition key values in all documents

Testing both insert and upsert write behaviors

Adjusting writeBatchSize and parallelCopies settings

However, the issue persists.

Could you please confirm:

Whether there have been any recent changes to the ADF Cosmos DB connector or backend execution behavior?

Whether there are known issues related to partition key handling in Copy Activity?

If there are any recommended configurations or workarounds for this scenario?

We would appreciate any insights or guidance.

Thank you for your support.

Best regards,Hello,

We are currently experiencing an issue with our Azure Data Factory (ADF) Copy Activity when restoring data to Azure Cosmos DB.

The error we are receiving is:

Missing partition key header for point operation

What is unusual is that:

The pipeline configuration has not been changed

The Cosmos DB container schema (including partition key) remains unchanged

The source data is identical (we are reusing previously successful backup data)

The same process was working successfully about one week ago

However, we are now seeing partial failures, where some documents are written successfully while others fail with the above error.

Based on our investigation, it appears that the write behavior may have changed internally (e.g., from bulk execution to point operations), resulting in stricter partition key handling.

We have already tried all recommended approaches, including:

Explicit field mapping for the partition key

Verifying partition key values in all documents

Testing both insert and upsert write behaviors

Adjusting writeBatchSize and parallelCopies settings

However, the issue persists.

Could you please confirm:

Whether there have been any recent changes to the ADF Cosmos DB connector or backend execution behavior?

Whether there are known issues related to partition key handling in Copy Activity?

If there are any recommended configurations or workarounds for this scenario?

We would appreciate any insights or guidance.

Thank you for your support.

Best regards,
YUZUKI AYASE 116 Reputation points

2026-03-18T05:52:09.8366667+00:00

Additionally, we would like to highlight that:

The exact same pipeline works successfully in our Dev environment but fails in Production

The pipeline was deployed to Production using an exported ARM template, so the configuration should be identical
Smaran Thoomu 34,155 Reputation points Microsoft External Staff Moderator

2026-03-18T11:13:06.18+00:00
YUZUKI AYASE Thanks for the detailed explanation - this is very helpful.

The error “Missing partition key header for point operation” usually means that during some write requests, the Cosmos DB connector is not receiving the partition key value in the expected format or path.

Even if the data and pipeline look unchanged, this can still happen due to runtime execution differences such as:

Copy Activity internally switching between bulk and point write operations based on batch size, throughput, or retry behavior

Partition key value being null / empty / differently typed for some records

Differences between Dev and Prod Cosmos container settings (indexing policy, throughput mode, partition key path casing, etc.)

Dataset or mapping differences after ARM deployment (sometimes hidden serialization differences occur)

At the moment, there is no confirmed platform change in ADF connector behavior that would intentionally introduce stricter partition key validation.

Since the issue is:

intermittent

environment-specific (Dev works, Prod fails)

partial success

this strongly indicates a data shape / runtime execution path difference rather than a global regression.

To help narrow this down, could you please share:

Exact partition key path of the Cosmos container (including casing)

Sink dataset JSON configuration from both Dev and Prod

Sample failing document vs successful document

Whether hierarchical partition keys are used

Current RU mode (manual / autoscale / serverless)

Copy activity settings (writeBatchSize, parallelCopies, upsert enabled or not)

Also as a temporary mitigation, you can try:

Set writeBatchSize = 1 to force consistent execution mode

Use Data Flow instead of Copy Activity (uses different execution engine)

Validate partition key datatype consistency across all records

If this started suddenly without any deployment change, we can further check internally for potential service behavior differences once we review the above details.

Thanks again for the detailed troubleshooting already done.
YUZUKI AYASE 116 Reputation points

2026-03-18T14:45:28.28+00:00
Thanks for your response.

We would like to clarify that:

The database and container configurations are effectively identical

We are restoring the same dataset for different customers

The main difference is that ADF and Cosmos DB accounts are separate between Dev and Prod, although their configurations are nearly identical.

Given this, it seems unlikely to be a data or configuration issue.

Share via

Copy Merchant Data, Error: Failure happened on 'Sink' side. ErrorCode=UserErrorDocumentDBWriteError,'Type=Microsoft.DataTransfer.Common.Shared.HybridDeliveryException,Message=Documents failed to import. Error message:Missing partition key header for point

1 answer

Your answer