What causes DF-Dynamics-InvalidNullAlternateKeyColumn?

A source column used in the Dynamics alternate key is null for some incoming rows — Dynamics rejects null alternate key values. The alternate key field is not always populated in the source system (e.g. an external reference ID that is optional). A transformation step is producing nulls for the key column when no match is found (e.g. a left join that didn't find a match)

How do I fix DF-Dynamics-InvalidNullAlternateKeyColumn?

In the data flow, add a Filter transformation before the Dynamics sink to exclude rows where the alternate key column is null.. Alternatively, add a Derived Column transformation to replace nulls in the key column with a placeholder value — only if that is appropriate for your data model.. In ADF Studio, open the Dynamics sink settings and confirm which alternate key is configured under 'Alternate key name'.. Run a Debug data preview on the node before the sink and check for null values in the key column using the filter expression: isNull(yourKeyColumn).. If the source legitimately produces nulls for that field, reconsider whether alternate key upsert is the right strategy or switch to primary key matching.

Medium severitydata flow

Power BI Refresh Error:
DF-Dynamics-InvalidNullAlternateKeyColumn

What does this error mean?

The Dynamics sink is configured to use an alternate key for upsert matching, but one or more columns in that alternate key contain null values in the incoming data. Dynamics requires all alternate key columns to be non-null for row matching.

Common causes

1A source column used in the Dynamics alternate key is null for some incoming rows — Dynamics rejects null alternate key values
2The alternate key field is not always populated in the source system (e.g. an external reference ID that is optional)
3A transformation step is producing nulls for the key column when no match is found (e.g. a left join that didn't find a match)

How to fix it

1In the data flow, add a Filter transformation before the Dynamics sink to exclude rows where the alternate key column is null.
2Alternatively, add a Derived Column transformation to replace nulls in the key column with a placeholder value — only if that is appropriate for your data model.
3In ADF Studio, open the Dynamics sink settings and confirm which alternate key is configured under 'Alternate key name'.
4Run a Debug data preview on the node before the sink and check for null values in the key column using the filter expression: isNull(yourKeyColumn).
5If the source legitimately produces nulls for that field, reconsider whether alternate key upsert is the right strategy or switch to primary key matching.

Frequently asked questions

What is an alternate key in Dynamics and why is it used for upserts?

Dynamics alternate keys are non-primary-key fields defined as unique identifiers in the entity configuration. They enable upsert matching on a business key (like an account number) instead of the Dynamics internal GUID.

Will filtering out null-key rows cause data loss?

Filtering rows with null alternate keys prevents them from being written to Dynamics — they are skipped. If skipping is not acceptable, fix the null values upstream or reconfigure the upsert strategy.

How do I find which rows have null values in the key column?

In Debug mode, add a filter before the Dynamics sink with isNull(yourKeyColumn) and run a data preview — it will show all offending rows.

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