What causes DF-Cosmos-InvalidConnectionMode?

The Cosmos DB linked service connection mode is set to 'Direct' — Mapping Data Flows require 'Gateway' mode, which routes traffic through the Cosmos DB gateway endpoint. A linked service created for a Copy Activity was reused for a Mapping Data Flow without checking the connection mode setting, which has different requirements between activity types

How do I fix DF-Cosmos-InvalidConnectionMode?

Open the Cosmos DB linked service in ADF Studio.. Locate the 'Connection mode' property and change it to 'Gateway'.. Test connection confirm the updated configuration is valid.. Save the linked service and re-run the failing data flow.

Medium severitydata source

Power BI Refresh Error:
DF-Cosmos-InvalidConnectionMode

What does this error mean?

The ADF Mapping Data Flow Cosmos DB linked service specifies a connection mode that is not valid for the connector type or account configuration. Cosmos DB Mapping Data Flow connectors require the 'Gateway' connection mode.

Common causes

1The Cosmos DB linked service connection mode is set to 'Direct' — Mapping Data Flows require 'Gateway' mode, which routes traffic through the Cosmos DB gateway endpoint
2A linked service created for a Copy Activity was reused for a Mapping Data Flow without checking the connection mode setting, which has different requirements between activity types

How to fix it

1Open the Cosmos DB linked service in ADF Studio.
2Locate the 'Connection mode' property and change it to 'Gateway'.
3Test connection confirm the updated configuration is valid.
4Save the linked service and re-run the failing data flow.

Frequently asked questions

What is the difference between Gateway and Direct connection mode in Cosmos DB?

Gateway mode routes requests through the HTTPS gateway (port 443) and works through firewalls. Direct mode uses TCP to Cosmos DB backend nodes — it requires open ports and is unsupported by ADF Mapping Data Flows.

Does changing to Gateway mode affect performance?

Gateway mode has slightly higher latency than Direct mode for individual requests, but for batch data flow operations the difference is negligible. Gateway mode is the only supported mode for this connector.

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