What causes DF-Cosmos-InvalidPartitionKey?

The partition key path in the Cosmos DB sink settings does not match the container's actual partition key (e.g., sink says '/customerId' but container uses '/tenantId'). The partition key path format is incorrect — Cosmos DB requires a leading slash (e.g., '/category'), which may be missing in the sink configuration. The container uses a nested partition key path (e.g., '/address/city') but the sink configuration only references the top-level property

How do I fix DF-Cosmos-InvalidPartitionKey?

In the Azure portal, go to your Cosmos DB account → Data Explorer → select the target container → Scale & Settings and note the exact partition key path.. Open the Cosmos DB sink transformation in ADF Studio and update the partition key path to match the container exactly, including the leading slash.. Enable data flow Debug mode and preview the sink input to confirm the partition key column contains non-null values for every row.. Re-run the pipeline after saving the corrected sink settings.

Medium severitydata source

Power BI Refresh Error:
DF-Cosmos-InvalidPartitionKey

What does this error mean?

The ADF Mapping Data Flow Cosmos DB sink specifies a partition key path that does not match the actual partition key defined on the target container. Every write operation fails because Cosmos DB cannot route documents to the correct partition.

Common causes

1The partition key path in the Cosmos DB sink settings does not match the container's actual partition key (e.g., sink says '/customerId' but container uses '/tenantId')
2The partition key path format is incorrect — Cosmos DB requires a leading slash (e.g., '/category'), which may be missing in the sink configuration
3The container uses a nested partition key path (e.g., '/address/city') but the sink configuration only references the top-level property

How to fix it

1In the Azure portal, go to your Cosmos DB account → Data Explorer → select the target container → Scale & Settings and note the exact partition key path.
2Open the Cosmos DB sink transformation in ADF Studio and update the partition key path to match the container exactly, including the leading slash.
3Enable data flow Debug mode and preview the sink input to confirm the partition key column contains non-null values for every row.
4Re-run the pipeline after saving the corrected sink settings.

Frequently asked questions

Where do I find the correct partition key path for my Cosmos DB container?

In the Azure portal, open the Cosmos DB account → Data Explorer → select your container → Scale & Settings. The partition key appears under 'Partition key'.

What format should the partition key path be in?

Cosmos DB partition key paths use JSON pointer format with a leading slash — e.g., '/userId' or '/address/city' for nested properties. Omitting the slash causes this error.

Can I change the partition key on an existing Cosmos DB container?

No — Cosmos DB partition keys are immutable. If the wrong key was chosen, you must recreate the container and migrate data.

Official documentation: https://learn.microsoft.com/en-us/azure/data-factory/data-flow-troubleshoot-guide