What causes DF-Dynamics-TooMuchAlternateKey?

The 'Alternate key name' setting in the Dynamics sink references a key that combines more columns than the entity's alternate key definition allows. Multiple alternate key names have been configured in the sink settings where only one is permitted. The Dynamics entity's alternate key definition was modified in Dynamics after the data flow was created, changing the number of key columns

How do I fix DF-Dynamics-TooMuchAlternateKey?

In ADF Studio, open the Dynamics sink settings and look at the 'Alternate key name' field — confirm only one key name is specified.. In your Dynamics environment, go to Settings > Customizations > Entities > [Entity] > Keys and check how many columns the specified alternate key uses.. If you need to match on multiple business keys, define a single multi-column alternate key in Dynamics and reference that one key name in ADF.. Remove any extra alternate key names from the ADF sink configuration so only one key name is listed.. Save the data flow, re-publish, and run a Debug test to verify the sink accepts the key configuration.

Medium severitydata flow

Power BI Refresh Error:
DF-Dynamics-TooMuchAlternateKey

What does this error mean?

The Dynamics sink is configured with more alternate keys than the target Dynamics entity supports, or more than the ADF connector allows for a single upsert operation. Each Dynamics entity supports a limited number of alternate key definitions.

Common causes

1The 'Alternate key name' setting in the Dynamics sink references a key that combines more columns than the entity's alternate key definition allows
2Multiple alternate key names have been configured in the sink settings where only one is permitted
3The Dynamics entity's alternate key definition was modified in Dynamics after the data flow was created, changing the number of key columns

How to fix it

1In ADF Studio, open the Dynamics sink settings and look at the 'Alternate key name' field — confirm only one key name is specified.
2In your Dynamics environment, go to Settings > Customizations > Entities > [Entity] > Keys and check how many columns the specified alternate key uses.
3If you need to match on multiple business keys, define a single multi-column alternate key in Dynamics and reference that one key name in ADF.
4Remove any extra alternate key names from the ADF sink configuration so only one key name is listed.
5Save the data flow, re-publish, and run a Debug test to verify the sink accepts the key configuration.

Frequently asked questions

Can a Dynamics entity have multiple alternate keys defined?

Yes — a Dynamics entity can have several alternate key definitions, but each ADF sink operation must reference exactly one by name. Multiple alternate key names cannot be specified in a single sink configuration.

How do I find the correct alternate key name to use?

In Dynamics 365, go to Settings > Customizations > Customize the System > Entities > [Entity Name] > Keys. The 'Name' column shows the schema name to use in ADF.

What if I need to match on more than one business key field?

Define a multi-column alternate key in Dynamics that includes all required fields, then reference that single key name in the ADF sink for composite matching.

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